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THINGS TO KNOW 

develop, The Apple Technical 
Journal, a quarterly publication of 
Apple Computer’s Developer Press 
group, is published in March, Junej 
September, and December, develop 
articles anti code have been reviewed 
for robustness by Apple engineers. 

This issue's CD. Subscription issues 
of develop are accompanied by the 
develop Bookmark CD/[’his CD contains 
a subset of the materials on the monthly 
Developer CD Series y available from 
APDA. Included on the CD are this 
issue and all back issues of develop along 
with the code diat the articles describe. 
(The code is updated periodically, so 
always use the most recent CD.) The 
CD also contains Technical Notes, 
sample code, and other documentation 
and tools (these contents are subject to 
change). Items referred to as being on 
“this issue’s CD” are located on either 
the Bookmark CD or the Reference 
Library or Tool Chest edition of the 
Developer CD Series, The develop issues 
and code are also available in the 
Developer Services areas on AppleLink 
and eWorld and at ftpjnfo.apple.com. 
Selected articles are on the World 
Wide Web at http://www.apj5le.com, 
in the Developer Services area. 

Macintosh Technical Notes. 

A designation like “(QT 4)” after a 
reference to a Macintosh Technical 
Note in develop indicates the category 
and number of die Note on this issue’s 
CD. (QT is die QuickTime category.) 

E-mail addresses. Most e-mail 
addresses mentioned in develop are 
either AppleLink or eWorld addresses. 
We Ye currently in transition: a given 
AppleLink address may no longer work 
by the time this issue is published. 

If that happens, try the equivalent 
eWorld address. On the Internet, 
AppleLink address XXX translates to 
xxx@a p pie 1 i nk. apple.com, eWorld 
addresss XXX to xxx@eworld.com, 
and NewtonMail address XXX to 
xxx@on lin e. a pple. co m. 
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APDA (see ordering information 
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hack issues from APDA. For all 
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name, address, and account number as it 
appears on your mailing label 

The one-year U.S, subscription price is 
£30 (for 4 issues and 4 develop Bookmark 
CDs), or LLS. $50 in other countries. 
Back issues are $13 each. These prices 
include shipping and handling. For 
Canadian orders, the subscription price 
includes GST (R1002 36199), 
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EDITOR'S NOTE 



CAROLINE ROSE 


I was visiting my friends Helen and John one night when Helen started telling me 
how excited about the World Wide Web John had become. He said, “Ask me 
anything at all, and I can find the answer for you.” I asked what the new U.S. postal 
rate for international air mail was, knowing it had recendy gone up from $.50. He 
delighted over finding a Web page for the Postal Service, and quickly found the rater 
$.50. Wrong. 

Later John showed me a spiffy magazine called NewMedia, and in it an article by 
longtime hypertext proponent Ted Nelson. Nelson expressed his joy that, with 
HTML and the Web, hypertext’s time has finally come; we can now leave the 
insanity of “paper simulation” behind and write in a way that lets information take on 
its truer, interconnected form, 

I found the article, and John’s enthusiasm over the Web, a bit disconcerting. The Web 
is indeed a boon to humankind, but I don’t see it entirely replacing what came before. 
The world’s love affair with the Web reminds me of the early days of TV (so I’m 
told), when many people were sure that radio was dead. Out with the old, in with die 
new. But in fact die old still had its place in the world. The virtues of the Web don’t 
mean we no longer need to get information from flesh and blood people sometimes, 
or from books and other media that we can hold in our hands. This may seem obvious, 
but from the near hysteria surrounding the Web these days, I’m not sure it is. 

A few days after my visit with Helen and John, with John still smarting from his 
failed demonstration of the wonderfulness of the Web, Helen called and mentioned 
that she needed the lyrics to “House of the Rising Sun.” I could hear John in the 
background, tapping away as he searched for them online, I said I’d use old 
technology and call back with them soon. The race was on. 

After looking through my loose leaf binders full of song lyrics and a couple of big 
songbooks, I dug through my tapes and found an ancient recording of Woody 
Guthrie singing the song. After lots of rewinding and transcribing, I had more verses 
than Helen ever dreamed existed. When I triumphantly called back, John (several 
levels down in the Library of Congress) was mortified. 

While old technology w ill typically not beat Web browsers in the search for nuggets 
of information, it will not die, and it deserves proper respect. There are some things 
we’ll learn only through person-to-person contact And there are emotions we’ll 
experience only from hearing or reading good old-fashioned sequential deliveries. 
The World Wide Web is a valuable resource, but it is not, after all, the world. 



CAROLINE ROSE 



Caroline Rose 
Editor 
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LETTERS 


PROJECTOR AG IMPRESSES 

Fve been working with Tim Maroney's 
ProjectDrag (Issue 23, “MPWTips and 
Tricks; Customizing Source Control 
With Source Server”), and I’m very 
impressed. I’ve never found an adequate 
way of using a revision control system 
on the Macintosh (Projector is too 
clumsy to use when you're developing 
with CodeWarrior), and I had written 
off SoureeServer completely after I had 
such a miserable experience with it 
under Symantec C++ 7,0, But Tim’s 
article and software have given that dog 
some new tricks. His programs are easy 
to use and powerful at the same time. 

Thank you very much for publishing 
Tim’s work in this issue, and I hope to 
see more about ProjectDrag in the 
future. 

— Phil Sulak 

Thanks for the feedback; we’re happy to 
know that you find ProjectDrag useful. 

There were a few problems with the previous 
version of ProjectDrag, so on this issue’s CD 
you’ll find a new version with a few hug 
fixes and enhancements. Also , the previous 
version was missing the makefile; its now on 
the CD. 

— Caroline Rose 

QTMA 

I read the article on QTMA by David 
Van Brink in Issue 23, and have a few 
additional questions. As Director of 
Audio for Human Code (an Austin 
multimedia developer), Fm looking for 
a way to convey an other-worldly quality 
to the soundscape of a CD-ROM title 
we're developing. 


First, is QTMA supported on the PC 
platform? If it only works on the Mac 
OS platform, I’m back to the drawing 
board. 

Also, is it possible to seed a bank of 
custom-designed samples to be played 
using standard MIDI files with QTMA? 
If so, is there a developer’s guide 
available for programming within 
QTMA? 

—John Malcolm Smith 

First of all , you’ve probably noticed that 
there were no changes to the Music 
Architecture in QuickTime 2.1 after all. 
These changes have hem delayed until the 
next release of QuickTime (which should 
ship by early 1996). The code on this issue’s 
CD has been revised so that it compiles with 
the 2.0 or 2.1 headers. 

On the PC side, QuickTime music tracks 
are supported, but only inside movies. So , 
compose your score on the Macintosh , 
import it into a QuickTime movie using 
MoviePlayer, and then save it flattened with 
the “Playable On Non-Apple Computers” 
box checked. This movie will play through 
Windows’multimedia extensions, according 
to its MIDI setup. 

As far as adding your own instruments, 
you should be able to do this in the next 
QuickTime release in two ways: by dropping 
a component into the System Folder .; to 
make a sound library available to all 
applications , or by inserting a sound into the 
music track of a particular movie . 

— David Van Brink 

PUZZLE PAGE DOESN'T STINK 

Re Lance Drake's letter in Issue 22 
entided “Puzzle Page Srinks”: I strongly 


IF YOU LIKE US, LET US KNOW 
What do you like, or not like, about develop 
(besides the Puzzle Page)? We welcome your 
letters, especially regarding articles published in 
develop. Letters should be addressed to Caroline 
Rose —* or, if technical deve/oprefated questions, 
to Dave Johnson — at AppleLink CROSE or 


JOHNSON.DK. Or you can write to Caroline or 
Dave at Apple Computer, Inc,, 1 Infinite Loop, 
Cupertino, CA 95014. All letters should include 
your name and company name as well as your 
address and phone number. Letters may be 
excerpted or edited for clarity (or to make them 
say what we wish they did).* 


LETTERS 3 





disagree. The Puzzle Page is die first 
article I read* From it Fve teamed new 
debugging tactics, and picked up cool 
Macs Bug tricks and how to do more 
dian just “G” from Micro Bug. The fact 
that the “scoring” shouldn't be taken 
literally is obvious; after all, KON & 
BAL never get the answer till 10 or less. 
Don't let one humorless whiner min a 
good thing. 

Keep up the good work; develop is a 
great resource. 

— Steve Palmen 

1 wanted to let you know how much I 
enjoy the Puzzle Page. I just graduated 
and was lucky enough to land a job 
programming on the Mac. Issue 22 is 
my first and IVe already looked back at 
all of the previous Puzzles because 1 
enjoy reading about the deepest, darkest 
Mac knowledge that I hope to stuff into 
my brain one day. Ids refreshing to have 
a technical journal that's not afraid to 
crack a joke every couple of pages. I 
haven't felt offended or mocked by your 
Puzzle Page. 

— Matt Glazier 

1 just want to let you know that there 
are people out here who read and enjoy 
the Puzzle Page. I try to follow every 
twist and turn in the logic that leads to 
the final result. Fve tracked down a few 
bugs in my own code that were complex 
and obscure enough to end up on the 
Puzzle Page, and ids nice to see the 
steps someone else follows. 

— David Shayer 

. . . WELL, MAYBE JUST A LITTLE 

The letter from Lance Drake in Issue 
22 about the Puzzle Page was, as you 
wrote, a surprise to you. To me it wasn't. 

First I would like to state diat the 
Puzzle Page is by far the best column in 
develop — technically very interesting 
and also amusing. This explains the 
good feedback you receive on it. Yet the 
“scoring” tables are indeed belittling, 


elitist, and intellectually arrogant. Even 
worse, they are offending. This is a 
detail, but it fully explains and justifies 
Mr. Drake's angry letter. 

— Adriaan van Os 

Many thanks for all the work you put 
into develop . The production qualities 
are superb. I have only one complaint: 
get rid of KON & BAL's Puzzle Page. 

I always feel depressed after reading it. 

— Andrew Trevor row 

FINGER CODED BINARY 
VARIATION 

I'd like to comment on Tobias Englers 
Finger-Coded Binary column in Issue 
21. Although I agree with most of what 
he said, Tobias's approach, the 10-bit 
model, is far less natural than it needs to 
be. 1 find it much easier (at least more 
natural) to work with hands flat on the 
side of a table, using all fingers except 
thumbs — this results in the more 
commonly used 8-bir model. You can 
then use your thumbs for other things, 
such as branch prediction, status 
registers, or even complex instruction 
execution. 

1 have one advantage over many people, 
'The fact that Pm missi ng part of my 
right thumb enables me to do fractions. 
No other digital system I know of can 
do 0, 1/2, and 1 digits. 

— Martin-Gilles Lavoie 

There's much more to the 10-hit model 
than you seem to realize. Have you ever 
had somebody tell you “You can eat as many 
Snickers bars as you can count on your 
hands '7 Probably not. You wouldn't leant to 
stop at 256 , would you? 

Concerning your fractional thumb: Your 
technological advantage over conventional 
digital systems will undoubtedly attract 
many copyists, which may result in a lot of 
unnecessary bloodshed. My advice to you is 
go and get a patent! 

— Tobias Engler 
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Speeding Up whose Clause Resolution 
In Your Scriptable Application 


The Object Support Library provides convenient mechanisms for 
scriptable applications to support complex expressions that m,ay return 
multiple results (such as every item of container "b" whose name 
contains "a"). However, the petformance of applications that rely on 
the default behavior is nowhere near what it could be if the application 
took on some of the work itself This article shows you how to gain 
ten- to a hundred-fold increases in the performance of whose clame 
resolution in your scriptable application. If your application is not yet 
scriptable , you’ll find that the foundation classes presented in this article 
do most of the work required to support scripting. 



GREG ANDERSON 


One of the greatest strengths of AppleScript is its built-in ability to do complex 
operations on groups of objects in a single line of script* For example, suppose you 
have a set of shapes in a scriptable drawing program, and you’d like to change the 
color of all the red shapes to green. In conventional programming languages, you’d 
need to write a loop that iterates over each object in the set, tests to see if its color is 
red, and then does a “set color to green” command for each red object that was 
found. Using AppleScript, you can do the same operation w ith the single statement 
set color of every shape whose color is red to green. In that statement, every 
shape whose color is red is called a whose clause , and it’s the inclusion of whose 
clauses that makes AppleScript the powerful language it is. 

You may at first doubt that using a whose clause is much better than writing the 
equivalent script with a loop. After all, the direction of modem processor design has 
been toward simplicity of the instruction set; RISC chips are able to gain incredible 
performance improvements by doing optimizations that aren’t possible in CISC 
chips* Also, when all is said and done, the whose clause must finally execute the same 
loop-and-compare algorithm that you’d be forced to use if you wrote the script with 
the basic fiow-of-comro] script commands, such as do-while and if-then. 


Using a whose clause is, however, much more efficient than the alternative* 
AppleScript is based on the client/server paradigm: typically your script, the client, 
w ill be running in one application (usually the Script Editor or a script saved as a 
miniapplication), with the application being scripted acting as a server. In this 
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situation, each script command that’s directed at the scriptable application needs to be 
transferred between the two applications. A whose clause is a single script command, 
but with the loop approach many commands would need to be sent. Furthermore, 
AppleScript allows the scriptable application to reside on a different machine than the 
application running the script; if your script is running on a machine in Cupertino, 
California, and the server is on, say. Mars, reducing the number of round-trip 
messages would have a profound impact on the performance of the script. Remember, 
you can currently get only about 30 round-trip Apple events per second, so even if 
you aren’t sending data to Mars, you’ll still do a lot better with fewer events than with 
many. 

There’s another, similar reason that using whose clauses is superior to the equivalent 
loop-based script: AppleScript compiles scripts into byte codes that are interpreted 
during execution, whereas the individual script commands (once interpreted) are 
processed by a scriptable application typically written in a language that’s compiled 
into machine code (be it 680x0 or PowerPC™). The loop-and-compare script will 
execute several lines of script for every item that’s compared, whereas the whose 
clause is but a single line of script that triggers processing in a compiled application. 

It should be quite clear which will take less time to execute. 

The Object Support Library (OSL) — the library that provides the API you use to 
make your application scriptable — enables your application to support whose 
clauses without requiring you to write a lot of additional code. You only need to 
provide an object-counting function and an object comparison function, and the OSL 
can resolve whose clauses for you. Since supporting whose clauses allows script 
writers to write more efficient scripts, you should always do at least this much. 
However, there are two other features of the OSL that can vastly increase the 
performance of scriptable applications but are often ignored by application writers: 
whose clause resolution (a way for your application to find the objects that match a 
whose test without using the OSL) and marking (a mechanism for efficiently 
handling collections of objects, such as those satisfying a whose clause). Using whose 
clause resolution, with the help of marking, will enable you to get the most out of 
your scriptable application. Resolving whose clauses can be a bit tricky, but with a 
little help from this article, you’ll be on your way in no time. 

If your application is not yet scriptable, you’ll find the sample code included with this 
article (and on this issue’s CD) to be invaluable in getting you up and running — 
particularly since it contains a lot of reusable code. 

AN OVERVIEW OF THE OSL 

Good descriptions of the OSL can be found in the develop articles “ Apple Event 
Objects and You” in Issue 10 and “Better Apple Event Coding Through Objects” in 
Issue 12, If you need a quick review of the OSL and you don’t feel like putting down 
this issue of develop to dig through your back issues, read on. If you can already 
generate tokens and resolve object specifiers in your sleep, by all means skip ahead 
to the next section. 

When AppleScript is processing a script command such as delete paragraph 2 of 
document "sample", k converts the command into an Apple event which it sends 
to the scriptable application that’s referenced by the script. The Apple event’s event 
class and message ID together specify the verb of the operation being performed — 
in this case delete. The object being operated on is passed in the keyDirectObject 
parameter of the Apple event, which is called, naturally enough, the direct parameter 
of the event. 
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The direct parameter is almost always an object specifier — a descriptor of type 
typeObjectSpedfier — although in some cases it may be something else. For 
example, in addition to object specifiers, the Scrip table Finder accepts alias records 
and file specifications in the direct parameter of events sent to it. If the direct 
parameter of an event is not of type type ObjectSped tier, you’re on your own to 
convert it into some format that’s understood by your event handler. For descriptors 
that are of this type, though, all you need to do is call the function AEResolve, and 
the OSL will step in anti help your application resolve the object specifier — that is, 
locate die Apple event objects it describes. 

Object specifiers are resolved dirough object accessor callbacks that your application 
installs to allow die OSL to communicate with your application during object 
resolution. The accessor callbacks must take the description of the object requested 
by the OSL (for example, document "sample") and return a token that describes the 
object in terms that die application can understand (for example, a pointer to a 
TDocument object). Tokens are passed back to the OSL in an AEDesc, a structure 
that contains a 32-hit descriptor type and a handle. Your application has complete 
control over what it stores in the token, as long as the AEDesc is valid (that is, it was 
created with AECreateDesc). 

When die OSL calls your application’s object accessor callbacks, it always passes 
either a token that represents the containing object (which it got from an earlier call 
to one of your object accessors) or a representation of the default container of the 
application, which is also called the null container of the application. So, to resolve 
the object specifier paragraph 2 of document "sample”, the OSL first asks for 
document "sample" from the null container. Then it asks the application to provide 
a token for paragraph 2 from the token the application provided in response to the 
request for document "sample". The token that the application provides for 
paragraph 2 is returned as the result of the AEResolve call; the application will 
presumably use this token to process the Delete event. 

Resolving object specifiers h explained En Chapter 6 of Inside Macintosh: 

interapplication Communication. A figure illustrating the process of resolving object 

specifiers is on page 6-6. * 


MARKING 

Inside Macintosh: Interapplication Communicatim describes marking as a mechanism 
whereby items to he operated on are marked with some flag during resolution (that 
is, from the callbacks made by the AEResolve function); then, during execution, each 
marked item is processed and the mark is cleared. As described, marking doesn’t 
sound very interesting and appears to be useful only in fringe cases. 

Marking is actually very well suited for use as a general-purpose collection mechanism 
whenever the OSL needs to group tokens together to process an object resolution. 
For example, if the OSL is resolving the whose clause every shape whose color is 
red and there are multiple red shapes, die resul t of the call to AEResolve must he a 
collection of all the tokens that represent red objects. If your application supports 
marking, the OSL asks your application to create a special mark token to represent 
this collection. After your application provides the OSL with a mark token, the OSL 
will ask your application to add the tokens it provided for the red shapes to the mark 
token’s collection. When AEResolve completes, the mark token is returned as the 
result of the resolution. 
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If your application doesn’t support marking, the OSL will create collections of tokens 
for you by copying die data from your tokens into a descriptor list (an AEDescList). 





It calls the standard Apple Event Manager routines for creating descriptor lists, which 
copy the data out of the data handle of the AEDesc and then store the token data 
somewhere inside the data handle of the descriptor list; the descriptor type of the 
AEDesc is similarly encapsulated. 

Dealing with descriptor lists of tokens can be inconvenient, particularly if your 
application already supports collections of objects in some other way. The OSL 
marking mechanism gives you the flexibility to handle collections in anyway that’s 
convenient for your application. 

To support marking, you must pass the flag kAEIDoMarking to AEResolve and 
implement the three markingcallbacks that are passed to AESetObjectCallbacks: the 
create-mark-token callback (called just a “mark-token callback” in Inside Macintosh), 
the object-marking callback, and die mark-adjusting callback. The create-mark-token 
callback doesn’t need to do anything more than create an empty mark token. The 
OSL will dispose of this token as usual by calling your token disposal callback when 
the token is no longer needed. Listing 1 shows an example implementation of a 
create -mark-tc i ken cal 1 back. 


Listing 1* Create-mark-token callback 

pascal OSErr CreateMark(AEDesc centainerToken, DescType desiredClass, 
AEDesc* markTokenDesc) 

{ 

TMarkToken * ma rkToke n; 

markToken = new TMarkToken; 
markToken->IMarkToken (); 

markTokenDesc->descriptorType = typeTokenObject; 
markTokenDesc->dataHandle = markToken; 


return noErr; 

} 


The object-marking callback is passed a mark token created from the create-mark- 
token callback and some other token created by one of your application’s object 
accessor callbacks. Your object-marking callback should add a copy of the other token 
into the mark token (or apply a reference count to the token being added), because 
the OSL will dispose of the token added to your collection shortly after calling your 
object-marking callback. Listing 2 shows one implementation of an object-marking 
callback. 

T he mark-adjusting callback is called to remove (“unmark’') tokens from the collection. 
Oddly enough, its parameters specify which tokens in the range to keep; all tokens 
outside the specified range should be discarded. 

Implementing the marking callbacks is trivial. The only real work involved in 
Supporting marking is handling col lections of tokens when they’re ultimately received 
by one of your event handlers (handling Move events, for example). The amount of 
code required to handle the marking callbacks and maintain your own collections is 
minimal; in fact, the time you’ll save by not having to hassle with descriptor lists of 
tokens will more than make up for the implementation cost You’ll find more 
information on handling collections of tokens later in this article. Don’t put oft 
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Listing 2. Object-marking callback 

pascal OSErr TAccessor;:AddToMark(AEDesc tokenToAdd, AEDesc 
markTokenDesc, long markCount) 

{ 

AEDesc copy0 fToke n; 

TMarkToken* markToken; 

// We know that the OSL will only give us mark tokens created with 
// our create-mark-token callback, but real code would do a test 
// before typecasting, 

markToken = (TMarkToken *) markTokenDesc.TokenOb j ect(); 

// Add a copy of the token to the collection, because the OSL will 
// dispose of tokenToAdd after passing it to you* A reference- 
// counting scheme is good here. 
copyOfToken ~ CloneToken(tokenToAdd); 
markToken*>AddToCollection(copyOfToken ); 

return noErr? 

} 


marking as an optimization to be done later; incorporate it into the design of your 
application from the very beginning* 

For more details on the marking callbacks,, see insid# Macintosh; 

Interapplication Communication, pages 6-53 to 6-54. 


WHOSE CLAUSE RESOLUTION 

The only thing that a scriptable application needs to do to support whose clauses is 
provide an object-counting function and an object comparison function — the OSL 
will do the rest of the work. When the OSL does a whose clause resolution, however, 
it has no choice but to iterate over every element in the search set, repeatedly calling 
your application’s object accessor, object comparison, and token disposal callbacks. 
Huge performance gains can be realized if you resolve w hose clauses yourself, 
because youll avoid the overhead the OSL requires to make these callbacks. 

Passing the flag LAEIDo Whose to AEResolve tells the OSL that you’ll resolve the 
whose clause yourself The OSL calls your object accessor with the key form 
form Whose (see Listing 3). The key data is a whose descriptor — that is, an AERecord 
that describes the comparison to be performed in the search. Your application should 
interpret the whose descriptor and test every element of the container token to see 
if it matches the specified criteria. If the whose descriptor is too complex for your 
application, you can return the error code errAEEventNotHandled from your object 
accessor, and the OSL will do the resolution for you with the default techniques. This 
is very useful, as it allows you to maximize the performance of the most common 
whose clauses, yet still support complex whose descriptors that are likely to be 
encountered only rarely. 

The astute reader will notice that the scheme presented in Listing 3 is very similar to 
the process that the OSL goes through to resolve whose clauses. There are still 
optimizations that could be made to speed up the resolution further, but we’ll get to 
those later. To resolve whose clauses as shown in Listing 3, your application must be 
able to do the following: 
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Listing 3, Handling form Whose in the object accessor 

pascal QSErr MyObjectAccessor(DescType desiredClass, AEDesc container, 
DescType /*containerClass*/, DescType key Form, AEDesc keyData, 
AEDesc* resultToken, long /*hRefCon*/) 

{ 

switch (keyForm) { 

// case formAbsolutePosition, and so on 
case formWhose; 

// TWhoseDescriptor is a class that knows how to interpret 
//a whose descriptor and test tokens for membership in the 
// search set defined by the desired class and the whose 
// descriptor, 

TWhoseDescriptor whoseDesc(desiredClas s, keyData); 

// TTokenlterator is a class that knows how to iterate 
// over the elements of a token* 

TTokenlterator iter(container); 

for (iter.Reset(); iter,More(); iter * Next()) { 

AEDesc token = iter*Current(); 

if (whoseDesc,Compare(token) — kTokenlsInSearchSet) { 

// Add token to the collection stored in resultToken. 
AddTokenToResult(token, resultToken); 

1 

> 

break; 

> 

return noErr? 

1 


* Iterate over the elements of any token. 

* Determine class membership of any token. 

* Compare properties of the elements of any token. 

* Convert a whose clause into some internal representation usable by your 
application. 

The first two operations are required of any seriptable application, so yours probably 
can already do them. Comparing properties is something your application probably 
doesn’t do yet, but in the worst case you could always write a few lines of code that 
call your property object accessor function, retrieve the data from the resulting 
property token, and then compare the descriptor that was returned. Obviously you 
can do better than this in terms of performance, and lateT on well investigate how. 
First, though, we’ll look at how to interpret the contents of a whose descriptor, 

THE CONTENTS OF A WHOSE DESCRIPTOR 

Earlier I claimed that a whose descriptor was an AERecord, but I bed, A whose 
descriptor is actually a descriptor of type type Whose Descriptor. Internally, a whose 
descriptor is stored just like an AERecord, but you can’t extract its parameters unless 
you first coerce it to type typeAERecord. In Apple events parlance, this type of 
descriptor is called a coerced record ; its basic type is typeAERecord, and its coerced 
type is typeWhoseDescriptor. 
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The advantage of coerced records is that they allow clients of the Apple Event 
Manager (for example, the OSL) to define new descriptor types for AERecords that 
define the context in which the record will be used and specify (by convention) what 
parameters the client can expect to find inside it. The disadvantage is that it requires 
an extra memory allocation to coerce the descriptor back to typeAERecord before the 
parameters of the coerced record can be accessed. This is unfortunate, as one of the 
primary goals of performance optimization is to remove extraneous memory 
allocations; coercing the descriptor back to typeAERecord is part of the current 
design of the Apple Event Manager, though, so there’s nothing we can do about it 

There are two parameters inside a descriptor of type typeWhoseDescriptor: 
keyAEIndex and keyAETest 

* The keyAEIndex parameter usually contains an enumeration w hose value is 
kAEAll; this corresponds to the word every in the whose descriptor every 
item whose name contains The other possible values arc kAEFirst, 
kAELast, kAKMiddle, and kAEAny for whose clauses that request the first, 
last, middle, or any (random) item. The keyAEIndex parameter might also 
be of type type Lon glnteger or typeWhoseRange, to indicate a single item or 
a range of items, respectively, 

* The keyAETest parameter contains another coerced AERecord whose type 
can he either typeCompDescriptor or type! ^ogicalDescriptor, In either 
case, you must coerce the descriptor to type typeAERecord to access the 
parameters inside it, 

A comparison descriptor (typeCompDescriptor) contains three parameters: two 
objects to compare (keyAEObjectl and keyAEObjectZ) and a comparison operation 
to be performed on them (keyAECompOperator). Usually the first object to compare 
is a special type of object specifier that indicates a property to compare (for example, 
pName), and the second is a literal constant to compare it against (for example, 11 e"). 
The comparison operators include contains, begins with, ends with, equal, not 
equaf greater than, and a bunch of other relational operators* Because comparison 
descriptors can contain object specifiers (and usually do), they can become arbitrarily 
complex. You won’t be able to resolve them all unless you reimplement the entire 
functionality of the OSL, at which point you might as well not call AEResolve either 
(thank goodness for errAEEventNotHandl ed, which allows you to fall back on the 
OSL if your application cannot parse a whose descriptor). 

Fortunately logical descriptors arc much simpler than comparison descriptors. A 
logical descriptor contains two parameters: keyLogicalOperator and keyLogicalTerms. 
The logical operator indicates the Boolean logic to apply on the contents of the 
logical terms: and, or, or not. The logical terms descriptor is, as you may have guessed, 
a list of descriptors whose type is either typeCompDescriptor or type Logical Descriptor. 
Figure I shows the contents of a whose descriptor that corresponds to ihe script 
every item whose name contains "e TT and si&e is 0* 

The contents of whose descriptors ore described in Inside Macintosh: 

Interapplication Communication , pages 6-42 to 6-4 57 

PARSING WHOSE DESCRIPTORS 

It may look like there can he a lot of different cases to handle in a whose descriptor, 
but it actually doesn’t take too much code to convert a whose descriptor into a format 
that your application can understand. The next few listings show how this might be 
done. The code presented is somewhat simplified; it doesn’t look at the keyAEIndex 
parameter of the whose descriptor (kAEAll is assumed), and it recognizes only very 
specific formats of comparison descriptors. Even this much of an effort is very useful, 
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Figure 1 , Contents of a whose descriptor 

because it will cover about 90% of the whose clauses that your application is likely to 
encounter, and it’s stil] possible to return errAEEventNotl landled and allow die OSL 
to take over for the rest- If you’re expecting me to fall back on every develop author’s 
favorite phrase, “This impossible task is left as an exercise for die reader,” you’re in 
for a surprise. The sample code on the CD will parse any valid whose descriptor 
passed to it and never falls back on the default handling provided in the OSL. 

The top-level routine, ParseWhoseDescriptor, simply extracts the keyAETest 
parameter and passes it to Parse WhoseTest, returning the resulting search 
specification. These two routines are shown in Listing 4. (A search specification is an 
application-defined object that knows how to test tokens for membership in the 
search set defined by the whose descriptor; see the sample code on the CD for the 
implementation of the search specifications used in these listings.) Parse WhoseTest 


Listing 4. Interpreting the contents of a whose descriptor 

TAbstractSearchSpec* ParseWhoseDescriptor(TDescriptor whoseDescriptor) 

{ 

TAbstractSearchSpec* searchSpec = nil; 

TDescriptor testDescriptor; 

whoseDescriptor.CoerceInPlace(typeAERecord); 

// Real code would call whoseDescriptor.GetDescriptor(keyAEIndex} 

// and at the very least check to see that its value is kAEAll, 

// and fail with errAEEventWotHandled if it isn't. 

(continued on next page) 
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Listing 4. Interpret rig the contents of a whose descriptor (continued) 

testDescriptor - whoseDescriptor.GetDescriptor(keyAETest); 
searchSpec = ParseWhoseTest[testDescriptor); 
testDescriptor.Dispose(); 
return searchSpec; 

} 

TAbstractSearchEpec* ParseWhoseTest(TDescriptor whoseDesc) 

{ 

TAbstractSearchSpec* searchSpec - nil; 

switch (whoseDesc.DescriptorType()) { 
case typeLogicalDescriptor: 

TDescriptor logicalOpDesc, logicalTerms; 

DescType loglcalOp; 

whoseDesc.CoercelnPIace(typeAERecord); 

logicalOpDesc - whoseDesc.GetDescriptor(keyAELogicalOperator}; 
logic alOp - logicslOpDe s c.GetEnmneration{); 
logicaITe rms = who seD e s c. G etD esc r ip tor(ke yAELogic a1T erms); 
searchSpec = this->ParseLogicalDescrIptor(logiealOp, 

logicalTerms J; 

logicalOpDesc.Dispose{J; 
logicalTerms.Dispose(); 
break; 

case typeCompDescriptor; 

TDescriptor compGperatorDesc, objl# obj 2; 

De s c Type compOp; 

whoseDesc.CoercelnPlace(typeAERecord}; 

compOpe ratorDesc = whoseDesc,GetDescriptor(keyAECompOperator ); 

compOp = compOperatorDesc*GetEnumeratiorv(); 

objl ~ whoseDesc.GetDescriptor(keyAEGbjecti); 

obj2 = whoseDesc.GetDescriptor(keyAE0bject2J; 

searchSpec * this->ParseComparisoTiOperator(compOp, objl, obj2); 

coiapOperatorDesc • Dispose (J; 

objl-Dispose(); 

obj2 *Dispose(J; 

break; 

} 

return searchSpec; 


examines the type of the descriptor (either logical or comparison) and then extracts 
the appropriate parameters and passes them to either ParseLogicalDescriptor or 
ParseComparisonOperator, whichever is appropriate. 

Since logical descriptor records can contain one or more terms, each of which is 
either a comparison or a logical descriptor record, ParseLogical Descriptor calls back 
to ParseWhoseTest for each term in the record, creating a search specification for 
each (see Listing 5). If there’s more than one term, ParseLogical Descriptor compiles 
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Listing 5. Resolving logical descriptors 

T&bstraetSearchSpec* ParselogicalDescriptor(DescType logicalOperator, 
TDescriptor logicalTerms) 

{ 

TAbstractSearchSpec* searchSpec = nil, 

oneSpecification = nil; 

TDescriptor oneTem; 

TSearchSpecList* specificationList = nil; 

FOREACHDESCRIPTOR!SlogicalTerms, oneTem) { 
oneSpecification = FarseWhoseTest(oneTerm); 
if (specificationList -= nil) { 

if {(searchSpec «= nil) && (logicalOperator I- kAENot)) 
searchSpec = oneSpecification; 
else { 

specificationList = new TSearchSpecList; 
if (searchSpec) 

specificationList“>Add(searchSpec}; 
specificationList->Add(oneSpecification); 
searchSpec = nil; 

} 

} 

else { 

if (oneSpecification nil) 

specificationList->Add(oneSpecification); 

} 

> 

if (specificationList i- nil) 

searchSpec = new TLogicalSpec(logicalOperator, specificationList); 
if (searchSpec ** nil) 

FailErr(errAEEventWotHandled); 
return searchSpec; 

> 


the resulting search specifications into a list and returns that; otherwise, it returns a 
single search specification for die single term. 

Parse Com pa risen Opera tor (Listing 6) first tests to make sure that the comparison 
operator is of the correct format. (Again, the code in this listing recognizes only a 
specific flavor of comparison operator; see die code on die CD for a more complete 
example,) If the operator passes that test, a new search specification representing the 
comparison is created and returned. 

ABOUT THE SAMPLE APPLICATION 

The code presented up to this point is the easy part; implementing the marking and 
whose callbacks, parsing whose descriptors, and creating search specifications can all 
he done with a small amount of isolated code. Doing a search on a set of elements or 
performing a complex operation on a collection of tokens is a bit more involved, 
though, and requires a well-integrated framework that supports these concepts 
uniformly. You're in luck — the sample application included on this issue's CD has 
such a framework. 
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Listing 6. Parsing comparison descriptors 

TAbstractSearchSpec * ParseComparisonQperator(DescType comparisonOperator # 
TDescriptor& objectl, TDescriptor& object2) 

{ 

TAbstractSearchSpec* search Spec = nil; 

TDescriptor desiredClassDesc, containerDesc, 

keyFormDesc, keyData; 

if {(object1 *DescriptorType() l- typeObjectSpecifier) | 

(objects.DescriptorType(J = typeObjectSpecifier)) 
FailErr{errAEEventNotHandled); 

objectl* CoercelnPlace(typeAERecord); 

desiredClassDesc = objectl.Get DescriptorkeyAEDesiredClass); 
containerDesc = objectl.GetDescriptor(keyAEContainer); 
keyFormDesc = object 1 * GetDescriptor(keyAEKeyForm); 
keyData = objectl.GetDescriptor(keyAEKeyData); 
if (contai nerDesc * Descr iptorType () I = typeOb j ectBeingExainined) 
FailErr(errAEEventNotHandled); 
if (keyFormDesc.GetEnumeration{) == fomPropertylD) 

searchSpec - new TGenericSearchSpec(keyData,GetDescType (), 
comparisonOperator^ objects); 
desiredClassDesc,Dispose(); 
containerDesc.Dispose(); 
keyFormDesc.Dispose(); 
keyData,Dispose(); 
return searchSpec; 


The sample application is called Scrip table Database, As its name implies, it's a 
database that's fully scriptable; in fact, it J s usable only through AppleScript — it has 
no user interface whatsoever. Iris no coincidence that the model the database uses 
follows AppleScript’s element containment model very closely. The Scriptable 
Database has documents that can be created, saved, and opened. Documents contain 
elements; elements have properties and data and may contain more elements. The 
database itself is completely generic; it doesn’t care what the classes of the elemen ts 
are or what properties they contain. To use it for a specific application, you’ll have to 
edit Scriptable Database's dictionary, also called its AppleScript terminology extension 
(aete' resource), to add the terms you’ll need for your database. 

AppleScript terminology extensions are described in Inside Macintosh: 

Interapplication Communication , pages 7-15 to 7-20 and Chapter 8. 

All the techniques described in this article are implemented in the source code of the 
Scriptable Database application — in particular, the application supports marking, 
and it resolves whose clauses itself (very quickly, I might add). It’s an object-oriented 
application written in C++ based on a set of reusable foundation class libraries that 
you might find useful as a starring point in your own scriptable application. The 
source code is divided into the following subprojects: 

• The Database subproject contains a standalone C++ object database. The 
code in this project is not discussed in this article, but you might find it 
interesting to peruse. 
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* The Base subproject contains pure C++ code that has no dependencies on 
any Mac OS or Toolbox routines, or any code from any other subproject in 
Scriptable Database, 

* The Blue subproject contains C++ wrapper classes for Macintosh managers 
used by Scriptable Database. 

* The Foundation subproject contains the foundation classes that Scriptable 
Database uses to implement scripting, and as such Is the focal point of this 
article, 

* 7'he Scripting subproject contains the object accessors and event handlers 
needed to respond to the messages sent by AppleScript and the OSL, 

* The Application subproject contains all the code that defines the Scriptable 
Database application; in fact, all the code specific to Scriptable Database is in 
this subproject. Every other subproject is also used in some other application 
that IVe worked on. 

Note that these subprojects are layered such that each one uses code found only 
within that subproject or in a more primitive subproject. The Database subproject is 
used only by the Scripting and Application subprojects; all other subprojects are used 
freely by any subproject listed below it. The foundation classes will be discussed in 
depth in this article; comprehension of the rest of the sample code is left as an 
exercise for the reader. (You didn’t think I could write an entire article and not say 
that at least once, did you?) 

ABOUT THE FOUNDATION CLASSES 

The focal point of the foundation classes is the class TAbstractSeriptableObject. This 
class was designed to serve as a base class, but it may also be mixed into an existing 
class hierarchy with multiple inheritance, as was done in the sample application (see 
the class TScriptable Document). Any object derived from TAbstractScriptableObject 
can be used as a token for the OSL. Memory" management of tokens must be done 
carefully; note that in most instances, tokens passed to the OSL are temporary and 
must be deleted when the token disposal callback is called. In other instances, though, 
it may be more convenient to use an existing object that the application has already 
created — for example, a document object. 

Because of this, die token disposal callback must be able to unambiguously determine 
the difference between the temporary objects and those objects it should not delete, 
or disaster will result. Designators —objects diat represent some portion of another 
object — are used for the temporary objects. The class TAbstractScriptableObject 
defines the mediods CloneDesignator and Dispose Designator, which do nothing 
in the abstract case. Designators override these methods to copy and dispose of 
diemselves —sometimes in conjunction with a reference-counting scheme. 

As you might expect, die methods of TAbstractScriptableObject are designed to 
provide functionality that closely matches the features of the OSL, All objects derived 
from this class have elements and properties and can be sent events generated 
from an Apple event that the application receives. There are virtual methods in 
TAbstractScriptableObject that you can override to provide each of these types of 
behavior in your objects. 

ELEMENTS OF A SCRIPTABLE OBJECT 

A scriptable object exports its elements by providing an iterator object that knows 
how to iterate over the appropriate set of objects. There are two methods that return 
iterators, Elementlterator and DirectOhjectlterator. 
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virtual TAbstractScriptableObject* ParentObject(); 
virtual TAbstractObjectlterator* ElementIterator(); 
virtual TAbstractObjectlterator* DirectObjectlterator(); 

The ParentObject method returns the object that this object is an element oh The 
dement iterator iterates over the elements of the object, as was previously mentioned; 
the direct object iterator usually returns an iterator that knows about a single object 
— the TAbstractScriptableObject that created it- If the object is actually a collection, 
however, its direct object iterator will iterate over every element in the collection* 
Once your application provides an iterator for the elements of its objects, the code 
in the foundation classes can handle most of the standard access methods for you* 

The access methods supported include formAbsolutePosition and fomaName, the 
default ordinals (all, first, last, and so on), and ranges of items (for example, items 1 
through 10). 

Your application's scriptable classes can support more specialized access methods by 
overriding the appropriate method: 

virtual TAbstractScriptableObject* Access(DescType desiredClass, DescType 
keyFonn, TDescriptor keyData); 

virtual TAbstractScriptableObject* AccessByUniquelDfDescType desiredClass, 
TDescriptor uniquelB)j 

virtual TAbstractScriptableObject* AccessByOrdinal(DescType desiredClass, 
DescType ordinal); 

The first method, Access, is the general object-accessor dispatch method that calls 
the more specific access method appropriate for the keyForm parameter. You can 
override this method to define custom access forms — for example, the Scriptable 
Finder defined the forms form Creator (to access an application by its creator type) 
and formAlias (to access a file or folder through an alias record). The method 
AccessByUniquelD provides a mapping from a unique ID to an object; override this 
method if your objects have unique IDs that scrip ts can use to access them* The 
method AccessByOrdinal handles ordinal access* All ordinals defined in the Apple 
Event Registry are supported by the implementation in the base class, so your 
application will probably never need to override Access By Ordinal 

PROPERTIES OF A SCRIPTABLE OBJECT 

Every scriptable object has at least a few properties that it must support. Almost all 
classes will have these five properties; 

• pName, since most objects have names 

• pClass, pBestType, and pDefaultType, since the Apple Event Registry 
requires that all objects support these properties 

• pContents, since the foundation classes handle Get Data and Set Data events 
by using this property 

To advertise the existence of a property, your scriptable classes can override the 
methods BestType, DefaultType, and CanRetumDataOfType; these methods are 
used by the Get Data event handler to determine what data type it should ask for 
when it requests the property data from the object through GetProperty. 

virtual DescType BestType(DescType propertyName); 
virtual DescType DefaultType(DescType propertyName); 
virtual Boolean CanRetumDataOfType(DescType propertyName, 

DescType desiredType); 
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However, your application doesn’t have to override these methods to provide 
information about every property of an object, since it’s also possible (and more 
convenient) to describe the properties of an object in a property description table. 
For example, the properties defined in TAbstractScriptableObject are shown in the 
following property description table: 


TPrupertyOescription TAbstractScriptableObject;:fPropertiesOfClass[] 


{ pName, kReserved, 
{ pClass, kReserved, 
{ pDefaultType, kReserved, 
( pBestType, kReserved, 
{ pID, kReserved, 
{ plndex, kReserved, 


typeChar, 
typeType, 
typeType, 
typeType, 


typeChar }, 
typeType }, 
typeType }, 
typeType >, 


t ype LongInt ege r, t ypeLon gIn t eger 
typelongInteger, typeLongtnteger 


= ( 


) 


>; 


Each entry in this table consists of four long words: the property identifier, a long 
word reserved for use by the class that defines the property, the property’s best type, 
and the property’s default type. The property description table is referenced through 
die class data table, so properties defined in one class are automatically inherited by 
any class that derives from it. The methods BestType and DefaultType return 
information from die property description table if an entry for the requested property 
can be found, and the method CanReturnDataOfType returns true if the desired type 
is the best type or the default type for a property. 

See the files ObjecKcp and Object, h In the sample code for in format ion on the 
cfass data tables. The macros DedareMrnC lass Data and IrnplementMinClassDota are 
used for classes that have no class properties; classes that do have cfass properties 
use the macros DeclareClassData and ImplementClassDota, * 

The reserved long word from die property description table is always passed to the 
GetProperty and SetProperty methods; it can be used to provide information to assist 
in obtaining the data for the requested property. 


virtual TDescriptor GetProperty(DescType propertyName, DescType desiredType, 
unsigned long additionallnfo); 

virtual void SetProperty^Transaction* transaction, DescType propertyName, 
TDescriptor* data, unsigned long additionallnfo); 

The reserved long word can have nearly any value, but should not be greater tiian or 
equal to the constant kResercedRangeForPropertylnfo (see Abstract Seri ptableObjeet.h). 

In addition to making die application’s properties easier to implement, the property 
description table is key in supporting the “properties” property (which returns the 
current value of all the properties of an object, as specified by the property description 
table). It’s also very useful for accessing properties of collections of tokens, as described 
later. 


The transaction parameter in the SetProperty method must be provided by the caller 
but is not used by the foundation classes. It’s provided as a mechanism whereby 
transaction-based applications (such as Scriptable Database) can make all changes 
under the auspices of a transaction object. Once all changes are made successfully, the 
transaction changes are committed back into the database. If anything goes wrong, 
the transaction is aborted and all changes are backed out. To the foundation class, 
'["Transaction is just a named object that has no methods. The event handlers in the 
Scripting subproject use code from die Database subproject to create a transaction to 
pass to SetProperty (and other methods that can change the contents of die database). 
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and commit or back out of the changes as appropriate after the event completes 
successfully or fails. 

In some rare cases, it may be undesirable to include a property in the property 
description table, or it may be inconvenient to implement all of the functionality of a 
property strictly through the GetProperty and SetProperty methods. For example, 
Scriptable Finder has a trash property that returns a reference to the Trash object on the 
desktop. In such cases, your application should override the method Access By Property 
to return an appropriate scriptable object that represents the property: 

virtual TAbstract3cri.pt able Object* AccessByProperty[DescType 
propertyldentitier); 

The object returned by AccessByProperty can be any sort of scriptable object; 
unlike properties described solely by the property description table, it can have 
properties above and beyond the minimum (for example, pClass, pBestType, and 
pDefauItType), and it can receive events (such as Empty Trash). Properties diat are 
returned through AccessByProperty can also appear in the property description 
table, but if they do, the reserved long word should contain the magic constant 
kNeverCreateGenericProperty. 

SENDING EVENTS TO A SCRIPTABLE OBJECT 

Most scriptable applications use one of two dispatch techniques for handling Apple 
events: event-first or object-first dispatching. In event-first dispatching, an event is 
first dispatched to an event handler, which resolves the direct parameter and passes it 
a message appropriate to the Apple event being received. The advantage of event-first 
dispatching is that the parameters of the event are well known and can he extracted 
and passed to the object from the event handler, reducing the amount of duplicate 
code scattered through the various object event handlers. The disadvantage is that 
event-first dispatching requires a large number of very similar event handlers, and the 
message-passing API is often large (one method per event). 

Object-first dispatching attempts to solve this problem by providing a single event 
handler that blindly resolves the direct parameter of the received Apple event and 
passes the event to the resulting object. This technique is much simpler than event- 
first dispatching, requires a smaller API, and usually does exactly the right thing. But 
object-first dispatching doesn't always do exactly the right thing. For example, an 
Apple event that copies a set of objects to some destination container would send a 
different Copy event to every item in the source; what you might prefer is to have 
a single Copy event sent to the destination object, with the list of items to copy 
included as a parameter to the event. You'd never get the latter with object-first 
dispatching. 

The Scriptable Database application uses a combination of event-first and object-first 
dispatching. Most Apple events are processed by a common event handler that 
resolves the direct parameter and passes the message along, in object-first dispatching 
style. Certain special events, however, such as Move, Copy, and Create Element, are 
processed in their own event handler, which can send a message to some object other 
than the direct parameter of the Apple event. The two primary methods that events 
are sent to are AECommand and CreateNewEIement, 

AECommand is defined as follows: 

virtual TDescriptor AECommand(TTranaaction* transaction F TAEvent ae, 

TAEvent reply, long aeCommandID, TAbstractScriptableObject* 
auxObjects = nil, long auxlnfo = 0}; 
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Both the Apple event message and the reply are passed to the event handler, just in 
case they need to be accessed directly. The AECommand method should not put die 
command result into the reply directly, though, as it might not be the only object 
that’s receiving this message* Instead, it should return the result as the return value of 
the method, and allow die event handler to collect all the results into a descriptor list 
and package them in the reply. 

The meaning of the parameters auxObjects and auxlnfo depends on the event 
handler that’s processing the message; the aeCommandTD parameter implicitly 
defines what the AECommand method should expect to find in these parameters. 

For example, in the Move and Copy events, the auxObjects parameter contains the 
set of objects that should be moved or copied. Providing a single method with 
general-purpose, multiple-definition parameters allows different scriptable 
applications that use die same foundation classes to define new events that have 
custom parameters without requiring them to change or expand die API of the 
foundation classes. This is one of the advantages of object-first dispatching that we 
definitely want to keep in our design. 

The Create Element event is special enough to warrant giving it its own dispatch 
message: 

virtual TAbstractScriptableObject* CreateNewElement(Transaction* 

transaction, TAEvent ate, TAEvent reply, DescType newObjectClass, 
TDescriptor initialData, TDescriptor initialProperties, Boolean^ 
usedlnitialData, Boolean^ usedInitialProperti.es); 

In most cases, classes that override CreateNewElement only need to look at the 
newObjectClass parameter, create a new object of that class, and return a reference 
to the newly created object The event handler calls the SetData method of the new 
object by using the with data parameter from the Create event, and then calls the 
SetProperty method of the new object with each of the properties specified in the 
with properties parameter from the Create event. The initial data and initial 
properties for the new element are also provided as parameters to CreateNewElement 
in case they’re needed at create time. If the usedlnitialData or usedInitialProperti.es 
parameter is set to true, the event handler is inhibited from calling SetData or 
SetProperty, respectively, on the new object. 

TOKEN COLLECTIONS 

As previously mentioned, objects derived from TAbstractScriptableObject can be 
grouped into collections of tokens that can be passed around as a single object. The 
class that implements most of this functionality is TProxyToken, which is publicly 
derived from TAbstractDesignator. (A collection object is a temporary object created 
only to manage the collection of tokens and must be disposed of when the collection 
is no longer needed; therefore, a proxy must be a designator.) There are a number of 
different types of collections, each derived from the class TProxyToken. 

The classes of proxies provided in the foundation classes include the following: 

• TEveryltemProxy — every element of an object 

m TEn tire Contents — every item in the entire deep hierarchy 

• TxMarkTbken — a collection of tokens accumulated from the marking 
callbacks or from resolving a whose clause 

Other types of collections are also possible. For example, the selection token is a 
proxy for the set of items that are currently selected, so the token for the selection 
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would also derive from TProxyToken (however, since the Scriptahle Database has no 
user interface, it has no selection object)* 

Sending a message to a proxy token usually does nothing more than pass the message 
on to each of its delegates; for example, the open selection script would pass an Open 
event to every selected item* In other cases, however, the proxy token handles the event 
itself* For instance, set selection to item 1 doesn't send a Set Data event to the selected 
items; instead, it deselects the currently selected items and selects the items in the direct 
parameter (such as item 1 in the previous example). The exact behavior of the proxy is 
determined by the concrete class (for example, TEveryltemProxy) that derives from 
the abstract class TProxyToken, but die proxy token does provide some mechanisms 
that can be used by its descendants to control the meaning of certain messages. 

Properties in particular are bandied in a special way by proxies. Some properties will 
apply to the proxy object itself, whereas other properties will refer to the delegates of 
the proxy token. For example, the script default type of selection should return the 
default data type for the selection object (which would be of type typeAEList), 
whereas default type of every item whose name contains ,f e ,T should return a list 
of default types, one for each item that matches the query every item whose name 
contains M e". There is no heuristic that can be used to determine which properties 
should apply to the proxy and which should apply to the proxy’s delegates; die only 
solution is to list all the properties that should be sent to the proxy object in some 
way. In the foundation classes, this is done with the method Property AppliesToProxy: 

Boolean PropertyAppliesToProxy(DescType propertyName)* 

Each class that derives from TProxyToken should override PropertyAppliesToProxy 
and return true for those properties that should be processed by the proxy object and 
false for those that should be sent to the proxy’s delegates, 

MORE ON SEARCH SPECIFICATIONS 

Previous sections of this article described how a whose clause was received by the 
object accessors of an application, converted into a search specification, and then 
resolved with a simple element iterator. Now that you’re familiar with the capabilities 
of the foundation classes, we can go into the workings of the search specifications in a 
little more detail* 

As you may recall, there are two types of search specification: logical and comparative. 
The primary operation of a search specification is to take a token and return whether 
or not that item is a member of the set specified by the comparator. A logical 
specification contains a list of other specifications; it does nothing more than call 
the comparator method of each, and either logically AND or logically OR the 
results together. A comparative search specification needs to perform some test on a 
property of an object that was passed to it; it does so by calling the Comp are Property 
method of the object being tested. 

virtual Boolean CompareProperty{DescType propertyldentifier, DescType 
comparisonOperator, TDescriptor compareWith); 

The property identifier, the comparison operator, and tire literal data to compare 
with were all extracted from the whose descriptor, as described previously. The 
default implementation of CompareProperty calls the object's GetProperty method 
and compares the result with the literal data by using the specified comparison 
operator. (You’ll find a routine that compares two descriptors in die file MoreAEM in 
the Blue subproject of the sample application.) Note, however, that calling GetProperty* 
involves a memory allocation to create a descriptor for holding die property data. 
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Memory allocations are something best avoided in the inner loop of an operation 
that’s supposed to progress quickly, so the performance of a whose clause resolution 
can be improved if you override CompareProperty and do common property 
comparisons without a memory allocation. 

FURTHER OPTIMIZATIONS 

Using the techniques described up to this point, your application can resolve whose 
clauses, and do so much faster than the OSL would. However, there are other 
optimizations that you can make to further improve performance. 

The techniques described so far perform better than the OSL for two primary 
reasons: 

* They limit the number of memory allocations needed, as much as possible. 

* They reduce the number of callbacks that need to be made between the OSL 
and your application. This is particularly important if your application is 
PowerPC native but uses the emulated 680x0 OSL. 

Also, note that if your implementation of access by index is 0(N) rather than 
constant time, the OSUs whose clause resolution will be Q(N Z ), since it will have to 
call your 0(N) access by index callback N times. Even if you ignore this article 
completely and don’t resolve whose clauses yourself, you should as an absolute 
minimum cache die last token returned by your fonnAbsolutePosition accessor and 
ensure that the next call to the accessor can be done in constant time if the container 
token and desired class are the same and the index is 1 greater. This will speed up 
your whose clause resolution considerably 

However, even for all of the performance gains that these techniques provide, whose 
clauses are still resolved according to the same basic algorithm used by the OSL. As 
anyone who has dabbled in computer information-science theory knows, it’s often 
more advantageous to switch algorithms completely and put off fine-tuning until 
after the correct algorithm has been found. 

Unfortunately, it’s not possible to do any better than what we’ve already done in the 
general case (a direct linear search of the search space, comparing every item to the 
search specification in order). Doing a binary search isn’t possible unless your search 
space happens to be sorted by your search key — not very likely and in any event it’s 
impossible to know whether it is or not unless you have specific knowledge about the search 
space. Searching the entire contents of a deep hierarchy —- such as all the folders on a 
disk — is one type of search space that can often be optimized. 

In cases where the search space is well known, it’s often possible to abandon the idea 
of direct iteration and use some other algorithm to search. For example, if you’re 
writing code to search the entire contents of a disk, you would be much better off 
calling PBCatSearch, which walks through the entries in the catalog record in the 
order they happen to appear on the disk, ignoring the disk’s hierarchy This technique 
is so much faster than doing a deep traversal of the disk’s catalog that doing a deep 
search of some subfolder on a disk is usually much better accomplished by searching 
the entire disk and weeding out the matches that aren’t somewhere inside the search’s 
root container. In cases where you have access to a search engine with characteristics 
similar to PBCatSearch, you should go out of your way to try to use it. Of course, 
this may well require yet another conversion of the search specification, but the 
performance gains will outweigh the initial cost. The foundation classes presented in 
this article have hooks that allow the incorporation of existing search engines to be 
incorporated into the process of resolving whose clauses. 
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When a whose clause is being resolved, the task of doing the search is delegated to the 
iterator object returned by die root of the search. Putting the method in the iterator 
rather than in the object allows different types of iterators to provide different search 
algorithms, each optimized to its own search space. The iterator returned by the 
TEntireContents proxy has a special implementation of AccessBySearchSpec; instead 
of using die implementation it inherits from TAbstractlterator, it uses a method called 
SearchDeep in the element iterator of the root object The default i mplementation of 
SearchDeep does nothing more than compare every item in the deep hierarchy below 
each of its elements, and add those that match to the collection. This is really no 
different from what would happen if TEntireC on tents:; Access BySearch Spec just 
called through to Inherited "AccessBySearchSpec, but it does proride a hook enabling 
special iterators to insert their own search engines if they have a technique that will 
do deep searches faster than a straightforward deep iteration. 

Listing 7 shows the default implementation of SearchDeep; note that it does a 
deep search on each of the elements of the iterator rather than simply a single deep 
search. The reason for this is that iterators aren’t required to have a single root object 
that one could conceivably search deep from; once you have an iterator, the only 
knowledge at your disposal is the set of objects that the iterator “contains.” The 
information as to where the iterator came from isn’t available to every iterator, 
although some {such as TPeepIterator) do save a reference to it. 


Listing 7. Doing a deep search 

TAbstractScriptableObject* TDeepIterator::AccessBySearchSpec(DescType 
desiredClas a , TAbstractSearchSpec * searchSpec} 

{ 

TQbjectCollector collector; 

TAbstractObjectlterator* iter = fRootIteirt->EleTnentIterator{); 
iter->SearchDeep(&collectQr, desiredclass, searchSpec); 
iter->Eelease(}; 

collector,CollectorRequest(kWaitForAsyncSearchesToComplete); 
return collector,CollectionResuIt(); 


void TAbstractObjectlterator j;S earchDeep(TAbstractCollector* collector, 
DescType desiredClass, TAbstraetSearchSpec* searchSpec) 

( 

TDeepIterator deeplter(nil); 

for (this->Reset{); thiS“>More(); this->Next()) { 

TAbstractScriptableObject* elementToDeepSearch = this->Current(); 
deeplter•FocusOnNewRoot(elementToDeepSearch); 
for [deeplter,Reset[]; deeplter.More(); deeplter.Next()) { 
TAbstractScriptableObject* token = deeplter,Current(); 
if (token->DerivedFromOSLClass(desiredclass) && 
searchSpec->Compare(token)) 
collector->AddToCollection{token); 
else 

token->DisposeDesignator(); 
token = nil; 

(continued on next poge) 
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Listing 7* Doing a deep search {continued) 

if {elemen t ToDeepSearch->DerivedFromQSLClas s{desiredClass) & & 
searchSpec->Compare(elementToDeepSearch)) 
collector->AddToCollection(elementToDeepSearch); 
else 

elementToDeepSearch->DisposeDesignator {); 

} 

} 


In Listing 7, rather than having the deep search iterator create and return a collection 
of tokens, a collector object is passed in and given the responsibility of making a 
collection from the results of the search, which it’s passed one item at a time. This is 
done so that other parts of your scriptable application can call SearchDeep to do 
deep searches if they need to, and providing a collector object allows this code the 
flexibility to process the search results one item at a time, as they are found, rather 
than waiting for the entire search to complete. 

Note the following line in Listing 7: 

collector*CollectorRequest(kWaitForAsyncSearchesToComplete); 

A search engine that's hooked into this code path might, in a multithreaded 
application, execute asynchronously under its own thread* In these instances, the 
search engine needs a way to tell the collector that it's still running, and might call 
collector->AddToCoIleetion with more search results at any time. The search engine 
does this by attaching a dynamic behavior object to the collection that understands 
die kWaitForAsyncSearchesToComplete message (see “What Is a Dynamic Behavior?”). 
When this message is received, the search engine's collector behavior must block the 
current thread of execution until the search engine completes its search. 

The use of a collector object and a dynamic behavior object allows the searching code 
to be flexible, optimized independently of other search engines, and reusable, even to 
other code that might not have exactly the same needs as the scripting code. 

Also note the implementation of the functions TEveryltem::SearchDeep and 
TMarkToken:: SearchDeep. Both of these call the function Recursive SearchDeep, 
which calls SearchDeep on each of the elements of the iterator in turn. Without this 
special code path, a script such as (entire contents of every disk) whose name 
contains "mac" would end up using the slow deep-iteration search, and miss out on 
the optimized SearchDeep method of each disk. Calling the SearchDeep method of 
each disk independently enables different types of disks to have different types of 
search engines; for example, searches of remote disks might be optimized differently 
than searches of local disks, and not every type of volume supports PBCatSearch, In a 
framework that has provisions for optimizations, flexibility of design is extremely 
important. 

WHAT WAS THIS ARTICLE ABOUT, ANYWAY? 

It doesn't take too much work to vastly improve the performance of your scriptable 
application, and the techniques presented in this article will help you do just that. 
Resolving whose clauses yourself can speed up the execution of your event 
processing by a factor of ten to a hundred; a chance to gain that level of improvement 
is hard to ignore. 
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WHAT IS A DYNAMIC BEHAVIOR? 

A dynamic behavior is an object that can be attached to 
some other object to change its behavior dynamically at 
run time. Only objects that are specially written to accept 
behaviors can have behaviors attached to them, and 
only certain methods of that object can be dynamically 
changed by the behavior object. 

Methods that support dynamic behaviors contain additional 
code that first dispatches to any behavior attached to the 
object and then does the default action for that method. But 
the actual flow of control is somewhat different from that. 

Suppose you have an abstract class TObject that supports 
behaviors, and an abstract class TBehavior that provides 
an interface for an object that can dynamically change 
the behavior of any TObject-derived object. If TObject 
has a method called Command that the behavior could 
modify, the implementation of TObject::Command would 
look like this; 

TObject;;Command() 

{ 

TBehavior* behavior? 

behavior = this->FirstBehavior(}; 


if (behavior) 

behavior->CommandDyiiamicBehavior(); 
else 

this- >Comman doe fault Bahavior(); 


TBehavior;;CommandOynamicBehavior(} 

{ 

TBehavior* behavior; 
behavior =* this->NextBehavior{); 
if (behavior) 

behavior->CommandDynamicBehavior(); 
else 

this->Gwner()->CommandDefaultBehavior(}; 

} 

Given this definition for the Command method, some class 
derived from TBehavior could override the virtual method 
TBehavior; :CommandDynamicBehavior, and call Inherited 
to execute the default action of the method it's overriding. 
This allows behaviors to do both pre- and postprocessing. 
The cost to supporting behaviors is additional dispatch 
time, but the advantage is the powerful, dynamic 
extensibility of your objects. 


AppleScript is one of the most compelling technologies that Apple offers — the ability 
to record scripts, modify diem, and play them back later puts powerful automation 
into the hands of programming novices. However, AppleScript is only as cool as the 
scriptable applications available in die marketplace* If you’ve written a seriptable 
application, thank you. If you haven’t yet taken the OSL plunge, by all means read 
some of the material referred to in this article and dive in* {You might also want to 
take a look at the “According to Script” column tiiat follows this article.) In either 
case, you should find the sample code on this issue's CD to be a very useful aid in 
implementing fast and complete scripting support in your Macintosh application. 


RELATED READING 

* /ns ide Mactntosh: Interapplication Communication (Addi son-Wes!ey, 1993). 

* "Apple Event Objects and You" by Richard Clark, develop Issue 10, and "Better 
Apple Event Coding Through Objects" by Eric M. Berdahl, develop Issue 1 2. 
These articles provide good descriptions of the OSL. 
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graphical interface, and should he as intuitive as you 
can make it. In creating human-oriented senptabillty, 
your goal is to make it as natural and as easy as possible 
for users to write sentences to communicate with and 
control your application. You want users to be able to 
write sentences that are as close as possible to the way 
they might think about what they want to do. Prepare 
to open up the full functionality of your application 
through scripting -— you'll want to make it complete. 

The following plan will help you develop a clean 
vocabulary that allows users to easily work with your 
application. 


To wind up my first year of writing about scripting in 
develop, this time I'll solidify the sequence of steps 
involved in making an application scriptable. A few of 
these steps have been mentioned before, while some 
material is new; here all the steps are organized so that 
you can work out a strategy for implementing 
scriptabilify. You may be surprised at what you’ll find. 

THE WRONG WAY 

In die past, a programmer who was responsible for 
implementing Apple events support in a scriptable 
application usually set about this task in one of two 
ways: 

* writing the code for the event handlers and object 
accessor functions first, then, just before shipping, 
deciding what to call things and throwing together 
a dictionary at the last minute 

■ jumping into the design of an object model 
hierarchy (in an attempt to implement the Core 
suite), then writing the event handlers and object 
accessor functions, and, again, putting together the 
dictionary last 

These methods were fine back in the days when Apple 
events were used principally for direct communication 
between two applications — one program was usually 
die client of the other. But in today’s world of scripting, 
it is users who are the clients. So in order to accomplish 
the goal of creating a human-friendly scripting 
vocabulary, developers need different methods for 
development. 

THE NEW, BETTER WAY 

Since your scripting interface is also a user interface to 
your application, it should be as foil and rich as the 


PRACTICE YOUR WRITING 

The first set of steps will help you home in on the 
terms you’ll use in your vocabulary. 

Write down sentences. The very first thing to do is 
to write down as many sentences as possible describing 
actions that can be accomplished with your application. 
At this stage, don’t try to make real scripting commands; 
just write down basic ideas. For example: 

play movies 

grab the customers profile 
print pages 2 through 5 

translate this book from English to French 
send this message to Bob at the Redmond office 
find all the records containing "University* 
delete all paragraphs containing the word 
"Windows" 

Hove users write sentences* Users think differently 
about the way they accomplish things with applications 
than programmers do. Invite users of your application 
to write down some general sentences. Encourage them 
to think about how they want to accomplish what they 
do. Ask them to write the sentences as if they were 
directing the computer by speaking to it. (You can do 
this simultaneously with the above step.) 

Include users who are experienced with earlier versions 
of your application. These users don’t need AppleScript 
experience. Consider inviting your documentation 
writers and your support people to participate. You’ll 
see quickly how users think about your application 
from a task-oriented perspective. 

Don’t attempt to write code yet or design your object 
hierarchy around what users write. Just use this to help 
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you think in broad terms about how something might 
he accomplished. 

Write some commands. Write more sentences, this 
time attempting to make script commands. Try to fit 
them into die context of a possible scripting vocabulary 
This is an iterative process, through which you can 
distill your broad ideas into useful terms. 

When writing commands, keep one eye open for 
consistency — think a bit about existing AppleScript 
commands and objects. At this juncture, it may help to 
have some people with AppleScript experience write 
sample sentences to describe how diey want to control 
your application. 

The sentences should begin to take on the flavor of 
AppleScript statements, with verbs followed by objects. 
For instance: 

tell "emailer" to send the file "Weekly Report" 
to "Bob" at "Redmond" 

tell "Mail Order Store" to order item "CW056" 
with nextday delivery 
tell the front window to select the first 
paragraph containing "Macintosh" 

WRITING ANALYSIS 

In the next set of steps, you*11 develop your object 
model hierarchy from your early command writing. 

Analyze your initial commands. The consumers of 
your product may surprise you. Some of the sentences 
they write will be too large in scope, but others will be 
highly focused to specific tasks. You’re likely to find 
that they’ll focus on the action first, then the objects. 
From those sentences, begin to determine the common 
verbs and objects. For example: 

* verbs: play, get, set, translate, send, print, select, 
delete 

* objects: movie, customer, paragraph, document, 
record, message 

* properties: profile, leading 

* enumerators: English, French, PowcrTalk 

Make a crude object model hierarchy. Based on 
the analysis of your commands, make a first cut at your 
object model hierarchy. Although many object classes 
in your vocabulary are types of objects that can be 
physically manipulated by your application, objects in 
scripting do not have to correspond to the objects on 
your screen. Nor should they match the objects in your 
internal code created by the programmers. Rather, 
script objects should be the most natural representation 


of what the user is trying to manipulate. Often these 
three — scripting, onscreen, and internal — will be 
nearly the same, but they don’t have to be. 

Remember that consistency in a scriptable application 
is often accomplished through the liberal use of setting 
and getting properties instead of through large numbers 
of verbs. For more information, read the section 
“Designing Your Object xModel Hierarchy” in my 
article, “Designing a Scripting Implementation/* in 
develop Issue 21. 

WORK ON YOUR DICTIONARY 

The key to a clean, intuitive scriptable application is its 
dictionary. It’s now time to develop this all-important 
“window” to your application’s soul. 

Look at other application terminologies for 

consistency. Creating the AppleScript interface is a lot 
like creating the graphical interface. When designing 
dialog boxes, for example, most developers look at 
many other applications for examples of what works 
anti what doesn’t. Similarly, you should view and use 
the AppleScript terminology of other applications to 
see how well they work. Remember that AppleScript 
hasn’t been around long enough for strong guidelines 
to be developed. Often you can do better than another 
application (in some cases, you can learn what not to 
do), but you also want your application to share as 
many elements as make sense with other applications 
your users might be familiar with. (When in doubt, 
refer to and practice w-ith the Scriptable Text Editor; 
it’s clean anil simple.) 

Make your first rough ’aete' and write commands. 

When you’re ready, take a stab at making an ’aete'. 
Don’t expect ton much at this stage; just get comfortable 
with the structure of this resource* Write some 
commands with your crude ’aete'. You can even open 
up your aete' in the Script Editor and check the syntax 
of your commands against your dictionary. Even 
though you w'on’t be able to execute the commands, 
you’ll be able to practice writing sentences using the 
terms in your early dictionary. 

Adjust the ‘aete 1 , Looking at the commands written 
with your early terms, you’ll begin to see where the 
sentences look more or less natural, and where they’re 
awkward. Based on this, you can start improving on the 
terms in your aete'* 

Make more commands; have users write 
commands* At this point, you’re ready to write some 
serious commands. By now you should be able to write 
real sentences that follow the AppleScript command 
structure: verb [object] [keyword value] ... These 
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sentences should be similar in structure to standard 
commands that you can write for other scriptable 
applications. They should “feel” like AppleScript: 

play the movie "1984 Commercial” 

get the profile of customer "Caroline Rose” 

print pages 2 through 5 

translate the document "Tech Manual" from English 
to French 

set the leading of paragraphs 1 through 3 to 10 
send the document "Order 578" via PowerTalk 

Note that the me of the word “the” is allowed in many 
places in AppleScript Many of your users will include 
it in their commands. You should name your objects 
and properties so that they won’t sound awkward w hen 
preceded by the word “die.” And try to avoid property 
names that start with a verb. 

Give your sample aete f to users and ask them to begin 
writing scripts to see how good your terminology feels 
and how it integrates and interacts with other 
applications. This interaction is crucial to understanding 
the value of AppleScript, All this can be done before 
any code is connected to the commands in die aete\ 
(Be sure to tell them that they can’t run their scripts.) 

NOW TO YOUR CODE 

A well-conceived dictionary will serve as a specification 
for programmers. Only after you’ve gotten your 
vocabulary in fairly good shape and done some 
preliminary testing with users should you (or your 
programmers) begin to write the code behind the 
vocabulary. 

Write object accessor functions. It’s probably a good 
idea to begin writing some ofyour object accessor 
functions first, so that you’ll have something to test 
your Apple event handlers against. Accessor fuactions 
must cover all possible combinations of object classes 
and containers. However, accessor functions can be 
combined to handle more than one object class in a 
container if the objects are similar or lend themselves 
to code that can he shared. 

For example, the Scriptable Text Editor has an accessor 
function for document objects, such as windows, within 
the application (the null container). It has another 
accessor function for all text objects within documents, 
such as characters, words, and paragraphs, and a third 
accessor for text objects within other text objects, such 


as characters within words, or words within paragraphs. 
Characters, words, and paragraphs were combined 
because die code to handle each of them was easily 
shared. 

Also consider the language, framework, and structure 
ofyour existing code. Some frameworks, such as 
MacApp, use internal object member functions that 
are very similar to the accessor functions you’ll write, 
lending themselves to individual accessors for each 
object class. You’ll certainly want your accessor functions 
to make use of the existing internal functions. 

Write Apple event handlers. Now you’re ready to 
write the code to handle the Apple events. Since you’ve 
made the effort to lay the groundwork, this should he 
relatively easy. If your dictionary contains a lot of 
properties, consider implementing set and get early in 
the game. 

Test your code. AppleScript is very useful for testing 
your Apple event code. You can easily write AppleScript 
commands that accurately send Apple events to your 
application. This is considerably easier than writing test 
code to fake sending Apple events to yourself. Scrip ter 
from Main Event makes an ideal tool for this task 
because you can observe what’s going on in a script as it 
happens. 

Once the code is connected, let a wider audience try 
your scripting. See how well the previously written 
scripts perform. 

Clean up your dictionary. After you’ve gotten 
your code working, go back and carefully look over 
your aete' one more time. Make sure that you’ve 
organised the terms well and that your comments are 
understandable and innovative. Use the guidelines in 
my last column, “Thinking About Dictionaries,” in 
Issue 23. 

A NEW PLACE TO GET HELP 

There’s now a resource on the Internet for posing 
questions relating to scriptability issues. It’s a new 
mailing list: applescript-implementors@abs-apple.com. 
To subscribe, just send the following message to 
li stpro c@ahs. app le. com: 

SUBSCRIBE appiescript-implementors Your Name 
As always, happy implementing! 


Thanks to Eric Gundrum ond C. K, Haun for reviewing this 
column. * 
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Getting Started With OpenDoc Storage 


OpenDoc's structured storage model is an innovative departure from 
the traditional storage scheme. As you make the move into OpenDoc 
development, you need to understand the new storage model and its 
implications for the way data is stored and retrieved. This article 
introduces the new concepts and policies you'll need to know in order 
to use OpenDoc storage effectively. 



VINCENT LO 


In die traditional Macintosh user model, each application creates and maintains its 
own documents, storing each document in a separate file. A file has one creator 
signature and one file type, identifying the application it belongs to and the kind of 
document it contains. In OpenDoc, by contrast, a document can have multiple pam, 
created and maintained by different pun editors (called part handlers in earlier versions 
of OpenDoc), which are analogous to the standalone applications of the traditional 
model. Because all of a document’s parts are stored together in the same container 
(usually corresponding to a file), there lias to be a way for separate part editors to 
share access to the same container without interfering with each other. 

OpenDoc meets this need by providing a structured model for persistent storage 
(that is, for storing data from one session to the next). Each part is given its own 
storage unit in w'hich to store and retrieve data. The part can thus operate as a 
standalone entity, independent of other parts and their storage, OpenDoc maintains 
all of the storage units and notifies each part when to read or write its data. 


The same techniques that are used in dealing with persistent storage also apply to the 
various forms of data interchange between part editors, such as the Clipboard, drag 
and drop, and linking. Because all of these mechanisms use the same data storage 
medium {the storage unit), they all w'ork essentially the same way from the part 
editor’s point of view. For example, a part uses the same AIM calls to copy data to the 
Clipboard that it would use in writing the data to a file container. The same is true 
for drag and drop and for linking. Thus, once you learn how to work with OpenDoc 
storage units for file storage, you can use the same techniques to implement data 
interchange as well. 

This article assumes that you’re already familiar with basic OpenDoc concepts and 
terminology. If you need a quick introduction or refresher, see the article “The 
OpenDoc User Experience” in develop Issue 22. You can find additional information 
on some of OpeiiDoc’s technical basics in the articles “Building an OpenDoc Part 


VINCENT LO is Apple's technical lead For 
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Handler” in Issue 19 and “Getting Started With OpenDoc Graphics” in Issue 2L 
Developer releases of OpenDoc include the definitive documentation, the OpenDoc 
Programmer's Guide and OpmDoc Class Reference. Developer releases are available 
through a number of different sources, or you can request the latest release at 
AppleLink OPENDOC or at opendoc@applelink,apple,com on the Internet. The 
source code in this article is excerpted from a sample part included with the developer 
release. 

Because OpenDoc was developed jointly by a consortium of companies including 
Apple, IBM, and Novell, its interfaces are designed for cross-platform compatibility, 
using IBM's platform-independent Standard Object Model (SOM). OpenDoc 
method definitions, including the ones in this article, are commonly written in a 
language-neutral Interface Definition Language (IDL). The SOM compiler converts 
these into equivalent language-specific declarations for whatever source language you 
happen to be using. The method definitions shown in this article, for instance, are 
taken from the OpenDoc interface file StorageU.idl. To use these methods in your 
program, you must include the corresponding language-specific binding file (such as 
StorageU.xh for a C++ program), 

DRAFTS/ DOCUMENTS/ AND CONTAINERS 

The OpenDoc classes responsible for providing storage capabilities are QDContainer, 
ODDocument, QDDraft, and ODStorageUnit, Collectively, a set of subclasses 
derived from these four is known as a container suite. A container represents the physical 
storage medium in which a document is stored, such as a disk file. Different container 
suites share the same API, but may use different low-level storage mechanisms and 
operate on different physical storage media. For example, the Bento container suite, 
which will be shipped with OpenDoc 1.0, supports both file containers and in-memory 
containers. A part editor can thus use the same code to store a part's data either to a 
file or in memory. 

A single container may contain one or more documents, each of which in turn can 
include one or more drafts. A part ordinarily works with a draft, rather than direedy 
with a document or its container. Each draft: is a “snapshot” representing the state of 
the document at a particular point in its development. Together, the drafts embody 
the history of the document over time. 

A part may need to interact with its draft for a variety of reasons; 

# Persistent objects — Every persistent object (such as a part, a frame, or a 
link) is created by a draft. 

• Data interchange — A part asks its draft to copy transferred objects to and 
from a data-interchange container, such as the Clipboard or a drag-and-drop 
container. 

* Linking — A part uses its draft to create link specifications and copy data to 
and from link objects. 

* Permissions — A part may need to find out whether ids allowed to write to 
the draft. 

• Scripting — A part gets its scripting-specific identifier through its draft. 

STORAGE UNITS 

The basic entity of a container suite is the storage unit. Every persistent OpenDoc 
object has a storage unit in which to store and retrieve its data. Figure 1 shows a 
typical example. 
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Storage unit 


kODPropCon rents 


kTextEditorKind 

kGDMacIText 


kOD Prop Prefer red Kind 


kODlSOStr 


kOD PropDl sploy F ra m es 

| kQDWeakStofageUmtRels 


Figure 1 - Structure of a storage unit 

A storage unit consists of one or more properties, each of which in turn is associated 
with one or more values containing the data itself. The storage unit shown in Figure 
1, for instance, has properties named kODPropContents, kODPropPreferredKind, 
and kODPropDispfayFrames; the kODPropContents property has values of types 
kTextEditorKind and kODMacIText- 

Using multiple values allows a property to represent the same data in different forms. 
For example, a property holding a drawing may have three values representing the 
same data: one as a Macintosh PICT, one as a Windows metafile, and one in TIFF 
format. Although Open Doc cannot enforce the principle, part developers are urged 
to use multiple values within a property only for multiple representations of the same 
data, not for storing unrelated data items. 

The property names and value types shown in Figure 1 represent string constants 
of type ODPropertyName and ODValueType, respectively. For cross-platform 
extensibility, both of these types are defined as equivalent to an ISO string instead of 
a traditional Macintosh OSType: that is, they're 7-bit ASCII null-terminated strings, 
as specified by the International Standards Organization (ISO). The string values 
themselves are expected to follow a standard naming convention: for instance, the 
constants kODPropDi splay Frames and kODWeakStorageUnitRefc stand for the 
strings " Open Doc :P r operty: D isplay Frames " and "OpenDoc:Type:StarageUnitRefe", 
respectively. The Open Doc interface files StdPropsidl and StdTypes.idl define name 
constants for standard properties and value types; any property and type names that 
you define for yourself should follow the same naming conventions. 

FOCUSING A STORAGE UNIT 

The OpenDoc operations for manipulating values don't explicitly identify the value 
to operate on. Instead, you have to ficus the storage unit on the desired property or 
value before invoking the operation. The method for setting the focus is defined in 
class ODStorageUnit as follows: 

ODStorageUnit Focus(in ODPropertyName propertyName, 

in ODPositionCode propertyPosCode, 
in ODValueType valueType, 
in ODValuelndex valuelndex, 
in ODPositionCode valuePosCode}; 
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This allows you to set the storage unit’s focus in a variety of ways: 

* to a property by name 

* to a property by position relative to the current property 

* to a value by type within a property 

* to a value by position within a property 

* to a value by position relative to the current value 

Properties and values are ordered within the storage unit according to die sequence 
in which they were added. Values within a property are indexed from 1: that is, the 
first value has index 1, the second index 2, and so on. Positions relative to the current 
focus are specified with a position code . The same position code can refer to either a 
property or a value, depending on the current focus. For instance, if the storage unit 
is currently focused on a property, the position code kO JPosNextSib designates the 
next property; if the current focus is on a value, kODPosNextSib designates the next 
value. 

Another way to set the focus of a storage unit is with a storage unit cursor: 

QOStorageUnit FocusWithCursor(in ODStorageUnitCursor cursor); 

The cursor identifies a property by name or a value by its property name and its index 
or value type. Once created (with method CreateCursor or CreateCursorWIthFocus 
of class ODStorageUnit), the same cursor can be reused multiple times to refer to 
properties or values within the storage unit. 

Once you’ve focused a storage unit, you can create a storage unit view to refer to the 
same property or value again later without having to reset the focus: 

ODStorageUnitView CreateVIew(); 

The view responds to all the same access methods as the storage unit itself, but 
applies them to the property or value that had the focus at the time the view was 
created, rather than at the time the method is invoked. Tt does this by automatically 
resetting the underlying storage unit to the original focus, then forwarding the 
method call to the storage unit for processing, 

MANIPULATING VALUE DATA 

The operations for manipulating data within a storage value are stream-based, very 
much like reading or writing to a sequential file. Each value has a current offset 
position that controls where the next operation will take place, similar to the 
file mark in the Macintosh file system. In addition to reading and writing data 
sequentially, you can also insert or delete data at the current offset position. 

Class ODStorageUnit defines the following methods for manipulating value data: 

void SetOffset(in ODULong offset); 

ODULong GetQffset(); 

void SetValue{in ODByteArray valve); 

ODULong GetValue(in ODULong length, out ODByteArray value); 
void Insertvalue(in ODByteArray value); 
void DeleteValue(in ODULong length); 

The ODByteArray structure is used to pass data to or from a storage unit. 
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typdef struct { 

unsigned long juaximum; /* size of buffer */ 

unsigned long _length; /* number of bytes of actual data */ 

octet* _buffer; /* pointer to buffer containing the data */ 

> _IDL_SEQUENCEjOCtetj 

typedef _IDL_SBQUENCE_octet ODByteArray; 

(An octet is simply the SOM term for an 8-bit byte.) Listing 1 shows how to 
manipulate one of the values shown in Figure L 


Listing 1* Adding data to a value 

/* Focus the storage unit, using property name and value type. */ 
storageUnit»>Focus(ev, kOOPropContents, kODPosUndefined, kTextEditorKind, 
0 f kODPosUndefined); 

/* Set up the byte array, */ 

ODByteArray ba; 
ba._length = size? 
ba._maximum = size; 
ba._buffer = buffer; 

/* Set the offset. (This step isn't really needed here, since the 
Focus operation automatically sets the offset to 0. It's included 
for illustrative purposes only.) */ 
storageUnit->SetOffsetfev, 0); 

/* Add the value, */ 
storageUnit->SetValue(ev jr &ba); 


STORAGE UNIT REFERENCES 

Storage unit references allow one storage unit to refer persistently to another, A part 
can use this mechanism to access information stored in a storage unit (which may or 
may not belong to it) across multiple sessions. A draft thus consists essentially of a 
network of storage units connected to each other with persistent references. 

When a storage unit is cloned (copied to a data-interchange container), any other 
storage units it references are cloned along with it Since all storage units in a draft 
are interconnected, cloning any one of them may cause the whole draft to be cloned. 
Because this may he an expensive and unnecessary operation, Open Doc provi des two 
levels of storage unit reference: strong and weak. Only strongly referenced storage 
units are copied when the unit that refers to them is cloned. 

In Figure 2, frame A refers strongly to part A, which refers strongly to frame B, which 
refers strongly to part B. Thus if frame As storage unit is cloned, all four storage units 
will be copied. On the other hand, cloning frame B ? s storage unit will copy those for 
frame B and part B only, since frame R’s reference to frame A is weak rather than strong. 

An object can use strong storage unit references to refer to other objects that are 
essential to its functioning, such as embedded frames. Weak references are mainly for 
informational or secondary purposes: a part might use them, for instance, to refer to 
its display frames. 
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Figure 2. Strong and weak storage unit references 

LIFE CYCLE OF A PART 

Figure 3 shows the life cycle of a part and its associated storage unit. Because the 
part’s lifetime may span multiple editing sessions, it must be able to externalize its 
internal state (save it to persistent storage) in order to reconstruct itself from one 
session to the next. The part’s InitPart method, called when the part is first created, 
receives a storage unit as a parameter. The Externalize method can then use this 
storage unit to save the part’s state. Once externalized, the part can be released 
from memory and later reconstituted from external storage by a method named 
InitPartFromStorage. Unlike InitPart, [nitPartFromStorage can be called multiple 
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Figure 3. Life cycle of a part 


GETTING STARTED WITH OPENDOC STORAGE 


35 
















































times daring a partis lifetime, whenever the part needs to be reconstructed from 
external storage* 

Notice that externalizing a part is not the same as cloning it* Externalizing means 
writing the partis data to persistent storage, using a storage unit associated with the 
draft in which the part resides; cloning is transferring the part’s data to a data- 
interchange container such as the Clipboard, using a storage unit associated with the 
container. Although the two operations are different, they’re both based on the same 
ODStorageUnit API and can share much of the same code. 

Another related operation is purgings which reclaims memory space by eliminating 
unnecessary runtime data structures such as caches. Because such structures can 
usually be reconstructed from persistent data, many OpenDoc programmers believe 
that a part’s Purge method should always begin by externalizing the part’s data before 
deleting unused or unnecessary memory. While this might sound plausible in principle, 
the extemalization operation itself requires additional memory — die very thing 
that’s in short supply during purging. As a general rule, the Purge method should 
avoid invoking extemalization unless it’s absolutely necessary. 

All persistent objects carry a reference count, enabling OpenDoc to identify unused 
objects and reclaim the memory they occupy. The Acquire method, which creates a 
reference to a specified object, increments the objects reference count; die Release 
method destroys a reference and decrements the reference count. When the reference 
count goes down to 0, OpenDoc can safely delete the object from memory. 

INITIALIZATION 

The initialization method InitPart is called only once, to set up a part’s initial state* It 
should take the following actions: 

1. Call the parent class’s InitPart method to perform any initialization required 
at the parent level. 

2* Save the incoming part wrapper object (discussed below) in an internal field* 

3. Set up an internal permissions field to indicate that writing to the draft is 
allowed. 

4. Set up the partis runtime data structures. 

5. Set the part’s internal dirty flag to true* 

Listing 2 shows an example. Notice that the SOM compiler, in translating the method 
declaration from language-independent IDL into a specific source language, adds two 
additional parameters at the beginning of the parameter list: a pointer to the object 
executing the method (somSelf) and an environment pointer (ev) used for error 
reporting. All of our example method definitions in this article begin with these two 
parameters* 

Parent Initialization. It’s important for a part’s initialization method to call that of 
its parent class. The parent’s initialization method will in turn call diat of its parent 
and so on up the inheritance chain, ensuring that all of the partis inherited properties 
are properly initialized. Inherited properties set up by ODPart and its parents, such 
as GDPersisteotObject, include the following: 

* kODPropCreateDate contains the part’s creation date. 

* kODPropModDate tells when the partis storage unit was last externalized. 

* kODPropModUser contains the name of the last user who modified the 
part. 
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Listing 2. Initializing a part 
SOM_Scope void 

SQMLINK TextEditor_InitPart(SampleCodeJTextEditor * somSelf, 

Environment *ev, 

00StorageUnit * storageUnit, 

ODPart *partWrapper) 

{ 

SampleCodeJTextEditorData *somThis = 

SampXeCodeTextEditorGetData(somSelf); 
SOMMethodDebug("TextEditor", "InitPart"); 

SQMJTRY 

// Call the parent class's InitPart method. The parent will in 
// turn call its parent, and so on. 

parent_InitPart(somSelf, ev, storageUnit, partWrapper); 

// Store part wrapper object in an internal field. 

_fSelf » partWrapper; 

// Set a flag showing that this draft is not read-only. 

_fReadonlyStorage = kODFalse; 

// Call common initialization code to set up our initial state. 
somSelf->Initialize(ev); 

// Set the dirty flag to true. 
somS elf->S e tDirty(ev )t 

S0M_CATCE_ALL 

//No explicit code needed here: cleanup will be performed by the 
// destructor, which is called automatically when an error is 
// thrown. 


SOMJENDTRY 


Part wrapper. Every part is wrapped by another object, called its part wrapper. 

Clients of the pan object deal with it indirectly, through the part wrapper, instead of 
holding a direct pointer to the part object itself. The part wrapper receives all method 
invocations and delegates them to the actual part. This insulation of the part object 
allows the part editor to be changed at run time without affecting its clients. 

The InitPart method should save the part wrapper object in an internal field. Then, 
whenever the part needs to pass an object representing itself as a parameter, it should 
pass the part wrapper in place of itself. 

Draft permissions. A part editor needs to know whether a part is in a read-only 
draft. If so, its functionality may be restricted: for example, the part may not allow the 
user to change its contents, either through keyboard input or through menu operations 
such as Cut and Paste. Also, if die draft is read-only, its Externalize method need 
never be called on its parts or any persistent objects. When a part is created for the 
first time, its draft is guaranteed to be writable, so it should initialize its read-only flag 
to false. 
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Dirty flog. The purpose of a dirty flag is to let the part’s Externalize method know 
whether it needs to write out the part’s state to external storage. Externalrzation 
(especially to disk) can be a time-consuming and expensive operation; using a dirty 
flag can greatly improve performance by avoiding it whenever possible. 

When a part is first created, its storage unit is empty. Since the state has not yet been 
written out, the part should initialize its dirty flag to true; the flag should also be set 
to true whenever the contents of the part are changed. After saving the state and 
content data to external storage, the Externalize method should clear the flag to false, 
indicating that the state need not be saved again unless the part’s contents are 
changed. 

EXTERN ALIZ ATI ON 

A part’s Externalize method can be called at any time. Typically, it’s called by the draft 
when the user chooses to save the document Since a part has no idea when this may 
happen, it should always be ready to externalize itself. 

The Externalize method should do the following: 

1. Call die parent class’s Externalize method. 

2. Check that all required properties exist; if not, add them to the storage unit 

3. Clean up the part’s contents if necessary. 

4. Write out the part’s stale in formation and contents. 

5. Clear the part’s internal dirty flag to false. 

Listing 3 shows an example. 

The contents of a part must he written out to a special content property named 
kODPropContents. Like other properties, die content property can contain multiple 
values representing the same data in different forms. A value type used for content 
data is referred to as a part kind , 4b facil itate data interchange, part editors are 
encouraged to include one or more standard part kinds in their content property, 
much the way traditional Macintosh applications use common data formats like 
’TEXT' or ’PICT' when writing to the Clipboard. 

Each value in the content property should be a complete representation of the 
content data. A value may contain references to other storage units, but cannot 
depend on other values in the content property or on other properties in the part’s 
storage unit. Even if every other property and value were deleted from the storage 
unit, the part editor should still be able to reconstruct the part using just diat one 
content value. 

The ordering of values within the content property is completely determined by 
the part editor. An important principle, however, is that values that represent die 
underlying contents with greater fidelity should precede those of lesser fidelity: 
formatted text, for instance, should precede plain (unformatted) text. The first value 
should be the one that represents the content most faithfully. 

When a part editor reconstructs a part from on external storage unit there's a 
chance that the storage unit may have originally been written by some other part 
editor As a result, the content property may contain part kinds that the current port 
editor doesn't support, or the values may appear in the wrong fidelity order. Jn this 
case, the part's Externalize method should remove all existing values from the content 
property so that it can write out its own content data in proper Fidelity order . 3 
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Listing 3, Externalizing a part 
SOMScope void 

SOMLINK T e xtEditor E xt e rna1 i ze {SampleCode_TextEditor *somSelf, 

Env ir oninent * e v) 

< 

SampleCodeTextEditorData *somThis = 

SampleCodejrextEditorGetData(soraSelf); 
SOMMethodDebug(*TextEditor", "Externalize n J; 

SOM_CATCH return; 

// Ask parent classes to externalize themselves. 
parent_Externalize(somSelf f ev); 

// Check dirty flag, 
if (_fDirty} { 

// Get storage unit. 

ODStorageUnit *storageUnit = somSelf->GetStorageUnit(ev}; 

// Verify that the storage unit has the appropriate properties; 
// if not, add them. 

soniSelf->CheckAndAddProperties(ev # storageUnit); 

// Validate storage unit's contents and clean up if necessary. 
somSelf->CleanseContentProperty(ev, storageUnit); 

// Write out state information and contents. 
sQmSelf->ExternalizeStateInfo(ev, storageUnit, 0, kODNULL); 
somSelf->ExternalizeContent(ev, storageUnit, kODNULL); 

i! Clear dirty flag. 

_fDirty » kODFalse; 

> 

} 


A standard property named kODPropPreferredKind identifies the part kind that the 
user chooses to represent the data. If this property already exists, the part editor 
shouldn’t tamper with it; if it doesn’t exist, the part editor may create it and give it a 
value of type kODISOStr containing the name of the highest-fidelity part kind. 
When writing out the content data, the part editor should be sure to include a value 
in the format specified by this property. 

RECONSTRUCTION 

The InitPartFromStorage method is called whenever a part object needs to be 
reconstructed from external storage. This method should do the following: 

1. Call the parent class's InitPartFromStorage method. 

2. Save the incoming part wrapper object in an internal field. 

3. Set up an internal permissions field to indicate whether writing to the draft is 
allowed. 

4. Set up the part’s runtime data structures. 
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5, Read the content data from the storage unit into the runtime data structures, 

6, Clear the part's internal dirty flag to false. 

Notice that these are essentially the same steps we listed earlier for the InitPart 
method, except that the contents of the part's runtime data structures are read in from 
the storage unit instead of being initialized to standard values, and that the dirty flag is 
cleared to false instead of true to show that the part's contents agree with those in the 
external storage unit. Listing 4 shows an example of an InitPartFromStorage method. 


Listing 4, Reconstructing □ port 

SOM_Scope void 

SOMLXTfK TextEditor_InitPartFromStorage 

(SampleCode_TextEditor *somSelf, 
Environment *ev f 

QDStorageUnit *storageUnit, 

OOPart *partWrapper) 

{ 

SampleCodeJTextEditorData *somThis = 

SampleCode_TextEditorGetData(somSelf); 
SOMMethodDebug("TextEditor" f "InitPartFromStorage-); 

// Avoid initializing the part twice, 
if (fSelf kODNULL) 
return; 

SOMJTRY 

// Call the parent class's InitPartFromStorage method. The parent 
// will in turn call its parent, and so on. 

parent InitPartFromStorage(somSelf, ev, storageUnit, partWrapper); 

// Store part wrapper object in an internal field. 

_fSelf « partWrapper; 

// Set a flag showing whether this draft is read-only. 
_fReadOnlyStorage = (storageUnit->GetDraft(ev)-> 

GetPemis sions (ev) == kDPReadOn ly); 

// Call common initialization code to set up our initial state, 
somSelf->Initialize(ev); 

// Read in state data from external storage. 
somSelf->InternalizeStateInfo(ev, storageUnit); 

// Read in content data from external storage, 
somSelf->InternalizeContent(ev, storageUnit); 

S OM__C ATC H_ALL 

//No explicit code needed here: cleanup will be performed by the 
U destructor, which is called automatically when an error is 
// thrown, 

SGM_ENDTRY 

} 
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As we’ve already noted, the storage unit from which a part is reconstructed may have 
been created by a part editor other than the one reading it in. The OpenDoc binding 
subsystem uses the part kinds found in the storage unit’s content property to 
determine which part editor to invoke. If the original part editor cannot be found, the 
binding subsystem will look for another editor capable of reading the available part 
kinds. The contents of foe storage unit may thus be very different from what the 
current part editor expects. Here are a few points to note: 

* If the storage unit identifies a preferred part kind (diat is, if it contains foe 
property kODPropPreferredKind), the part editor should read its content 
data from the indicated value of the content property. If no preferred kind is 
specified (or if the part editor cannot handle a value of foe specified kind), it 
should iterate through foe available values looking for one it can handle. 

When it finds such a value, it should read the content data from that value 
into its runtime data structures. 

* The InitPartFromStorage method should not add its own properties to the 
part’s storage unit, but should leave that task to foe Externalize method 
instead. This is because foe user may close the document without modifying 
any of its contents. If the InitPartFromStorage method modifies the storage 
unit, the user will be prompted to save the document before closing it, even 
though the document has not been modified. 

* The part editor should not alter the part’s preferred-kind property 
(kODPropPreferrcdKind). 

WHAT NEXT? 

Needless to say, the only real way to get familiar with OpenDoc programming is to 
jump in and develop a part editor of your own. The techniques discussed in this 
article will help you manage your storage needs effectively. The rest is up to you and 
your imagination. 


RELATED READING 

* The OpenDoc User Experience" by Dove Curbow and Elizabeth Dykstro-Erickson, 
develop Issue 22. 

* "Getting Started With OpenDoc Graphics" by Kurt Plersol, develop Issue 21. 

* "Building an OpenDoc Part Handler" by Kurt Piersol, develop Issue 19. 

* OpenDoc Programmer's Guide and OpenDoc Class Reference , available as part 
of the OpenDoc developer releases. 

* The latest news on OpenDoc can be found on the World Wide Web at 
http://www.info.apple.com/opendoc or http.//www.cilabs,org, 


Thanks to our technical reviewers Dave Bice H 
Craig Carper, Ed Lai, and Steve Smith. 


GETTING STARTED WITH OPENDOC STORAGE 


41 






GRAPHICAL 

TRUFFLES 

Making the Most 
of QuickDraw 3D 


For those of us on Apple's QuickDraw 3D team, the 
highlight of SIGGRAPH '95 (the annual conference 
of the ACM's computer graphics interest group) was 
having the chance to work with developers who were 
showing QuickDraw 3D products* Considering that we 
only started working with developers in December 
1994, the number of applications already up and running 
is inspiring* By the time you read this column, 10 or 15 
QuickDraw 3D products will be shipping, including 
modeling and animation software, 3D hardware 
accelerators, 3D model clip art, and games* More than 
50 developers are actively working on products based 
on QuickDraw 3D, and those will ship in 1996. 

If you're not yet a QuickDraw 3D developer and don’t 
want to be left out, take a look at the develop articles 
“QuickDraw 3D: A New Dimension for Macintosh 
Graphics” in Issue 22 and “The Basics of QuickDraw 
3D Geometries” in Issue 23. This column gives a 
hodgepodge of additional information. 

IMPROVING ACCELERATOR PERFORMANCE 

One of the things that has attracted developers to 
QuickDraw 3D us seamless access to hardware 
acceleration. In addition to Apple's PCI accelerator 
card, hardware acceleration cards have been announced 
by Matrox, Yarc, Radius, and Newer Technology* If you 
really want your application to fly, you need to make 
sure that you're using the fastest Tenderer possible and 
that if a hardware acceleration card is installed, you're 
using the card. If you use die QuickDraw 3D API, 



NECK THOMPSON AND 
PABLO FERNICOLA 


QuickDraw 3D will take care of this for you, but there's 
something else you can do that might improve your 
application’s performance. 

Certain cards, including Apple's accelerator card, will 
yield better frame rates in some situations if you use 
what we call double buffer bypass, an option enabled by a 
flag. Double buffering causes all objects to be drawn 
first into a back buffer; this entire buffer is then copied 
to the front buffer (the window). If the scene you’re 
rendering is simple and thus takes very litde time to 
redraw — say, less than 1/10 of a second — enabling 
double buffer bypass is faster because it avoids having 
to copy memory from the back buffer to the front 
buffer. On the other hand, if you use this option with a 
complex scene, tearing may occur. Therefore, you may 
want to time a frame (and take into account the 
complexity of your models) before using double buffer 
bypass. To time a frame, call the Toolbox routine 
Microseconds, draw the frame, call Q3Renderer_Sync 
to make sure the frame has been fully drawn, and then 
call Microseconds again and subtract die start time 
from the end time. 

If you’re using QuickDraw 3D's interactive software 
tenderer, all the code you need to turn on double 
buffer bypass is shown in Listing 1* 

The interactive Tenderer can render using software 
only or using hardware acceleration. The interactive 
Tenderer is set by default to look for the best device 
possible, so if a hardware accelerator is installed, the 
accelerator will always be used. On occasion, though, 
you may want to switch from using hardware to using 
software (for demos or testing, for example). In this 
case you must explicitly request the software rasterizer, 
as follows: 

Q3InteractiveRenderer_SetPreferences(myRenderer, 
kQAVendor_Apple, kQAEngine_AppleSW }; 

INTERACTING WITH INPUT DEVICES 

QuickDraw 3D provides an input device abstraction 
layer that allows you to interact with different input 
devices without having to write special code for each of 
them. The sample application NewEra demonstrates 


NICK THOMPSON (eWorld NICKT], transplanted English soccer 
fan and member of Apple's Developer Technical Support team, 
thinks that this could be the year for the Arsenal Football Club. 
With the acquisition of Dutch star Dennis Bergkamp and England 
striker David Platt, things are looking up at Highbury. By the time 
you read this, the Premier League standings will tell if this is the 
dawning of a new era or more of the same "boring, bo ring. 
Arsenal/' as those charming Spurs Fans like to chant, : 


PABLO FERNICOLA (eWorld EscherDude], of Apple's Interactive 
Multimedia Group, is much more relaxed since shipping QuickDraw 
3D 1.0. He now has time to eat his dad's great barbecue, dally 
with his lovefy wife, and sleep — although the latter entails the 
challenge of trying to get his golden retriever, aptly named Mac, 
to give up some of the space he takes up in the bed. Pablo's latest 
research project is to find out exactly what the purpose is for those 
orange balls that one finds on high power transmission lines. 1 ' 
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interaction with tablets and other input devices; this 
application is available on the CD that comes with the 
book 3D Graphics Programming With QuickDraw 3D, 
and a newer version can be found on this issue’s CD. 

To take advantage of QuickDraw 3D’s input device 
layer, you need to create a tracker object and associate 
it with a controller object (created by an input device 
driver), as Listing 2 does. Once you’ve set up your 
tracker, you can poll it to get its new position and 
orientation, as shown in Listing 3. To reflect the 
change in your scene, you apply the values returned by 
the tracker to a transform object, affecting either a 
particular geometry or group (if an object was selected 
and being manipulated) or die camera, depending on 
the interaction model for your application. 

QuickDraw 3D’s input device abstraction layer also 
makes writing input device drivers easier For example, 
it took us about three days to write a driver for the 
Magellan device from Logitech, Inc., a 3D input device 


with six degrees of freedom. As illustrated in Figure 1, 
this device enables movement along the x, y, and z axes, 
as well as rotation about the three axes. 

SETTING THE CORRECT FILE TYPE 

When saving QuickDraw r 3D metafiles, you should set 
the file type as 3DMF', regardless of how the contents 
of the file are formatted (as plain-text or binary, or any 
combination of the different types of organization, such 
as database or stream). This will enable the file to he 
read or opened by other QuickDraw 3D applications. If 
youVI like your end users to read a file as text, add an 
Export As "Text option to your application and then set 
the file type to 'TEXT 1 , This is helpful for debugging 
(and for sending questions or bugs to Developer 
'technical Support). 

HAVING FUN WITH CUSTOM ATTRIBUTES 

By taking advantage of QuickDraw 3D’s custom 
attributes and extensible metafile format, you can have 
objects that encapsulate specialized data relevant to 


Listing 1, Turning on double buffer bypass 
// Create the Tenderer. 

if {(myRenderer = Q3Renderer_NewFromType(kQ3RendererTypeInteractive)) nil) { 

if {(myStatus * Q3View_5etRenderer(myView, myRenderer)) kQ3Failure) { // Handle the error. 

} // Set bypass. 

Q 31nt e ra ct i veRe n der e r_Se tDoub1eB u f f e rB y pa s s{myRen d e re r, kQ 3True); 

> 


Listing 2* Creating a tracker object and attaching it to a controller object 

theDocument->fFositionSN - 0; 
theDocument->fRotationSN = 0; 
theDocument->fTracker = Q3Tracker_New(HULL); 
myStatus = Q3Controller_Next(NULL, ScontrollerRef); 
while (controllerRef 1= NULL myStatus == kQ3Success) { 

Q3Controller_SetTracker(controllerRef, theDocument->fTracker); 
myStatus = Q3Controller_Next(controllerRef, &controilerRef); 

1 


Listing 3. Updating position and orientation 

// We received a null event; grab a new position and orientation for the model, 

TQ 3 Boolean position C h a nged; 

TQ 3 Boolea n rot ation C hanged; 

Q3Tracker_GetPosition(doc,fTracker, Sdoc•fPosition, NULL, & positionChanged, &doc.fPositionSN); 
Q3Tracker_GetOrientation(doc,fTracker, &doc.fRotation, NULL, firotationChanged, Sdoc.fRotationSN); 
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Figure 1. Magellan: a six-degreesof-freedom input device (courtesy of Logitech) 


your application. For instance, to navigate through the 
World Wide Web in 3D, you can attach Web data (like 
URLs) to QuickDraw 3D objects as custom attributes. 
When those objects or scenes are read into one of the 
many viewers supporting the URL custom attribute, 
the viewer can communicate through Apple events 
with applications like Netscape (or your favorite Web 
browser) to produce 3D navigation. You’ll find a sample 
application that shows this on this issue’s CD. 

Custom attributes also enable you to associate sound 
and other data with objects in your 3D scene. 

DEBUGGING 

There are two really handy techniques that you can 
use to diagnose problems you may he having with 
your QuickDraw 3D application* For both of these 
approaches to debugging your software, you’ll want to 
make sure that you have MacsBug installed on your 
machine and that you’re using the debugging version 
of the QuickDraw 3D extension supplied with the 
QuickDraw 3D development software. 

The first technique is to install error and warning 
handlers, described in our article in develop Issue 22. 
Error and warning handlers are particularly useful for 
telling you of potential problems with your use of the 
QuickDraw’ 3D library. If you don’t install error and 
warning handlers, you won’t know if you’re doing 
something that the library identifies as erroneous. 
Although we stated this in our original article, many 


developers missed its significance and thus have 
experienced longer debugging times than necessary 
and a great deal of frustration. 

The second technique is to use a software tool, the 3D 
debugger, included on this issue’s CD. This application 
enables you to examine the QuickDraw 3D heap and 
look at the different objects, their attributes, and their 
reference count. Please note that you’re looking under 
the hood, so you may encounter untyped blocks, and 
the reference count for objects may reflect references 
internal to the QuickDraw 3D system* 

LOOKING AHEAD 

We’ll continue to release great new QuickDraw 3D 
Features, so bring your applications along for the ride. 
By early 19% we expect to have all major existing 3D 
applications on the Macintosh using QuickDraw 3D, 
along with applications that developers port from other 
platforms. Many 2D applications will be making use of 
the 3D Viewer as well. 

Watch develop for further articles about other aspects of 
QuickDraw 3D. Meanwhile, von may want to check 
out the Addison-Wesley book 3D Graphics Programming 
With QuickDraw 3D (wh ic h i nd udes the Q u i ckDraw 
3D development software) and see this issue’s CD for 
the development software and the latest versions of the 
sample code and utility applications. And for the latest 
news on QuickDraw 3D, see our Web page ai 
h tip:// www. info.apple.co m/q d 3 d. 


For more information on making your application work with 
Magellan, contact Stephan llberg at Logitech by sending a message 
to stephan_ilberg@iogrtech.com.* 


Thanks to Robert Dierkes and fabro PettEnati for reviewing this 
column, and a special thanks to Dan Venolia and David Vasquez 
For supplying some of the code and applications discussed, 5 
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Sound Secrets 


The Sound Manager is one powerful multimedia tool for the Macintosh , 
but no one has ever accused it of being too obvious. This article explores 
some of the more subtle Sound Manager features, showing some simple 
ways to improve your applications use of sound. A sample application 
demonstrates features such as volume overdrive and easy continuous 
sound . 



KIP OLSON 


The Sound Manager has a long and distinguished career on the Macintosh. First 
released in 1987, it was completely revised in 1993 with the release of Sound 
Manager 3.0, The introduction of Sound Manager 3.1 in the summer of 1995 
brought native PowerPC performance, making die Sound Manager one of the most 
powerful multimedia tools around. However, getting the most out of the Sound 
Manager often means wading through many pages of Inside Macintosh: Sound, 

This article pulls together valuable Information about the Sound Manager, 
focusing on some of its little-known features that will ease your development of 
multimedia applications. The tips and techniques come straight from the Sound 
Manager development team at Apple and cover diverse areas of developer interest, 
including 

• parsing sound resources 


* displaying compression names 


* maximizing performance 

* adjusting volume 

* controlling pitch 

* playing continuous sounds 

* compressing audio 


Two of these topics, controlling pitch and compressing audio, require the use of 
Sound Manager 3.1, which is included on this issued CD, YoulL also find the 
SoundSecrets application and its source code on the CD. SoundSecrets demonstrates 
many of the techniques described in the article. To get the most out of this article, 
you should be familiar with the Sound Manager command interface and concepts 
such as sound channels, as described in Inside Macintosh: Sound. 


So, let’s get started unlocking some of those sound secrets! 


KIP OLSON was recently dispatched to the 
Copland team at Apple with orders to rewrite 
the Sound Manager (again). To keep things 


interesting, he promises to add even more obscure 
features, * 
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FIND WHAT YOU'RE LOOKING FOR 

On the Macintosh, sounds can be stored in a variety of formats, including ’and 1 
resources, AIFF (Audio Interchange File Format) files, and QuickTime movies. 
Applications often need to read these files directly and extract their sound data, which 
can be a daunting task, especially when you begin to deal with some of the new 
compressed sound formats introduced in Sound Manager 3.1 — for example, IMA 4:1, 

Fortunately, Sound Manager 3.0 introduced a couple of routines to help you navigate 
these tricky waters — GetSoundHeaderOffset and GecCompressionlnfo. Let's take a 
look at these routines, and put them to work with an example of parsing an ’snd 1 
resource taken from the SoundSecrets application. 

The md 1 resource format is described fully in Inside Macintosh: Sound, so we won’t go 
into detail here, except to say that embedded in the resource is a sound header and 
die audio samples themselves. Finding this embedded sound header is the job of 
GetSoundHeaderOffset. Ii takes a handle to an arbitrary snd * resource and returns 
the offset of the sound header data structure within that handle. 

However, once you find the sound header, your work is not complete; you must 
determine which of the three possible sound header structures it is. In the SoundSecrets 
application, the sound header is represented as a union of the three structures 
SoundHeader, ExtSoundl leader, and CmpSoundHeader. The encode field in these 
structures determines which union member to use when examining the header. 

After you’ve extracted the appropriate information from the sound header, you can 
use the GetCompress ion Info routine to determine the sound format and the 
compression settings. GetGompressionlnfo fills out and returns a Compressionlnfo 
record, which contains the OSType format of the sound, samples per packet, bytes 
per packet, and bytes per sample. You can use these fields to convert between 
samples, frames, and bytes. 

For a thorough discussion of GetCo m press ion Inf o, see (he Macintosh 
Technical Note w GeiCompre$$(onlnfo[]" [SD ]).* 

As shown in Listing 1, the SoundSecrets application uses GetSoundHeaderOffset to 
find the sound header structure, and then uses a case statement based on the encode 
field to extract the useful information from each type of header. The SoundSecrets 
application calculates the number of samples in the sound using information returned 
by GetCompressionInfo, 

CHOOSE THE RIGHT NAME 

Now that you’ve extracted the sound settings from an ’snd 1 resource, the next thing 
you’ll want to do is display this information to the user of your application. Settings 
like sample rate and sample size are easy to display, but what if the sound is 
compressed? All you’ve got is an OSType to describe the compressed sound data 
format, and not too many users are going to get much out of seeing something like 
’MAGI’ displayed on their screen. 

Fortunately, the Sound Manager makes it easy for you to find a string to display that 
does make sense. Using the Component Manager, you can look up the name of the 
audio codec used to expand the compressed sound, and use this name to describe the 
compression format to the user. 

This is done with the Component Manager routine FindNextComponent, which is 
passed a ComponentDescription record. By setting the component \ ype field of this 
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Listing 1 . Getting information from the sound header 


typedef union { 


SoundHeader s; 

CmpS o u ndH e ader c; 

ExtSoundKeader e; 


// Plain sound header 
// Compressed sound header 
// Extended sound header 


} CommonSoundHeader, *CommonSoundHeaderPtr; 

OSErr FarseSnd(Handle sndH, SoundComponentData *sndInfo f 

Compressionlnfo ^eomplnfo, unsigned long *headerOffsetEesuit, 
unsigned long *dataOffsetResult) 


{ 


Common SoundHeaderPtr 
unsigned long 
short 
OSErr 


sh; 

headerOffset, dataOffset; 

compressionlD; 

err; 


// Use GetSoundHeaderOffset to find the offset of the sound header 
// from the beginning of the sound resource handle* 
err ® GetSoundHeaderOffset{(SndListHandle) sndH f 
(long *) sheaderOffset); 
if {err l- noErr) 
return {err J; 

// Get pointer to the sound header using this offset, 
sh = (CommonSoundHeaderPtr) (*sndH + headerOffset); 
dataOffset = headerOffset; 

// Extract the sound information based on encode type* 
switch (ah->s.encode) { 

case stdSH; // Standard sound header 
sndlnfo->sampleCount = sh->a.length; 
sndInfo->sampleRate = sh->s*sampleRate? 
sndInfo->sampleSize = 8; 
sndInfo->numChannals = 1; 

dataOffset += offsetof(SoundHeader, sampleArea); 

compressionlD = notCompreaBed; 

break; 

case extSH: // Extended sound header 

sndIn£o->sampleCount = sh->e.numFrames; 
sndlnfo->sampleRate = sh->e*sampleRate; 
sndInfo->sampleSize = sh->e>sampleSize; 
snd!nfo->numChannels = sh->e.numChannels; 
dataOffset += offsetof(ExtSoundHeader, sampleArea); 
compressionlD = notCompressed; 
break; 

case cmpSHj // Compressed sound header 
sndInfo->sampleCount - sh~>c.numFrames; 
sndInfO“>sampleRate - sh->c.sampleRate; 
sndInfo->sampleSize - sh~>c.sampleSize; 
snd!nfo->numChannels = sh->c*numChannels; 


(continued on next page) 






Listing 1. Getting information From the sound header (continued) 

dataOffset += offsetof(CropSoundHeader, sampleArea); 
compressionlD = sh->c.compressionID; 
sndInfo->format = sh->c,format; 
break; 

default: 

return {badFormat); 
break; 

) 

// Use GetCompressionlnfo to get the data format of the sound and 

/! the compression information* 

comprnfo->recordSize = sizeof(Compressionlnfo); 

err ** GetCompressionlnfofcompressionlD, sndInfo->format, 

sndInfo->numChannels, snd!nfo->sampIeSize, complnfo); 
if (err noErr) 
return (err); 

// Store the sound data format and convert frames to samples, 
sndlnfo->format = complnfo->format; 
sndInfo->sampleCount *= compInfo->samplesPerPacket; 

// Return offset of header and audio data* 

*headerO£fsetResult = headerOffset; 

*dataOffsetResult - dataOffset; 

return (noErr); 


record to kSoundDecompressor, the componentSubType field to the OSType of the 
compressed sound data format, and the remaining fields to 0, you can search for the 
sound component that will decompress the sound. Once you have tine component, 
you can use GetComponentlnfo to obtain the component name, which is the 
descriptive string that makes sense to the user. The routine from Sound Secrets shown 
in Listing 2 finds the name of any compressed sound format, 

MAXIMIZE YOUR POTENTIAL 

The Sound Manager is almost always used in conjunction with other operations on 
the Macintosh. For example, QuickTime uses the Sound Manager to play a sound 
track while it’s drawing the frames of a movie, and games play sound effects and 
background music while animating the screen. That’s why the performance of the 
Sound Manager is of such great concern to many programmers: if the Sound 
xManager takes too much rime to do its work, QuickTime will begin to drop video 
frames and games or animations will run slower 

To get the best performance out of the Sound Manager, you first need to understand 
a little about how it plays a sound. The Sound Manager’s major function is to convert 
the sounds played by an application into the audio format required by the sound 
hardware on a particular computer. For example, the sound hardware on the Power 
Macintosh 8100 requires a stream of 16-bit, stereo, 44.1 kHz audio samples, so the 
Sound Manager must convert all sounds to this format during playback. 
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Listing 2. Finding the name af a compressed sound Format 

OSErr GetCompressioriNamefOSType compressionType, Str255 compressionName) 

< 

ComponentDescriptlon cd; 


Component 

Handle 

OSErr 


component; 

componentName; 

err; 


// Look for decompressor component, 
cd»componentType = kSoundDecompressor; 
cd.componentSubType - compressionType; 
cd.componentManufacturer = 0 ; 
cd.componentFlags = 0; 
cd.componentFlagsMask * 0 ; 

component » FindNextComponent(nil, &cd}; 
if (component nil) { 

err =* silnvalidCompression; 
goto FindC ompon entFailed; 


} 


// Create handle for name. 
componentName = NewHandle(0); 
if (componentName == nil) { 
err = MemError(); 
goto NewNameFailed; 

> 

// Get name from the Component Manager, 

err = GetComponentInfo{component, &cd, componentName, nil, nil); 
if (err != noErr) 

goto GetlnfoFailed; 

// Return name, 

Bloc kMoveData(* c omp on entName, c ompr essionN ame, 

GetHandleSize(componentName )); 

GetlnfoFailed: 

Dis po s aHa nd1e{c ompo ne nt Name}; 

NewNameFailed: 

FindComponentFailed: 
return (err); 

} 


It does this by examining the format of the sound to he played, and setting np the 
proper conversion steps needed to convert it to the hardware format. These steps 
might include decompression, sample size adjustment, sample rate conversion, 
volume adjustment, and mixing, all of which take time away from your application. 

Therefore, the best way to maximize Sound Manager performance is to simply supply 
it with sounds that are already in the format required by the sound hardware. This 
way, the Sound Manager doesn’t have to spend a lot of time processing, and your 
application will have more time to do other operations. Fortunately, Sound Manager 
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3.1 provides a new routine, SndGetlnfo, that helps you determine the current sound 
hardware settings, so maximizing performance is a snap. (Of course, this technique 
applies only to sounds the application generates itself, since otherwise you have no 
control over their format.) 

SndGetlnfo is a selector-based routine that returns information about the sound 
channel. You pass in an GSType selector, and it returns a data structure of information. 
(This is similar to the operation of the SPBGetDevieelnfo routine in the Sound Input 
Manager, and in fact they use the same selectors.) Once you know the sound hardware 
sample rate, sample size, and number of channels, you know the kind of sounds that 
will be played back most efficiently. 

The Sound Secrets application demonstrates how to determine the hardware settings 
and then find the sound with the correct format. It uses the GetHardwareSettings 
routine, which determines the hardware settings, and the FindMatthingSound 
routine, which chooses the right sound to play to maximize performance. 

Listing 3 shows how to use SndGetlnfo to return the current hardware settings. 


Listing 3* Getting the current hardware settings 

OSErr GetHardwareSettings(SndChannelPtr chan, 

SoundComponeiitData hardware Info) 

{ 

OSErr err; 

err = SndGetlnfo(chan, siNumberChannels, &hardwareInfo~>nuroChannels); 
if (err 1= noErr) 
return (err); 

err = SndGetlnfofchan, siSampIeRate, £hardwareInfo->sampleRate); 
if (err 1» noErr) 
return (err); 

err = SndGetlnfo(chan, siSampleSize, &hardwareInfo~>sampleSize); 
if (err noErr) 
return (err); 

if (hardwareInfo->sampleSize == B) 

hardwarelnfo->format - kOffsetBinary; 
else 

hardwarelnfo->fori?iat - kTwosComplement; 
return (noErr); 

> 


PUMP UP THE VOLUME 

Most sound programmers have heard (literally) about the venerable ampCmd 
command, which lets you scale the volume of all sounds on a channel from a minimum 
of 0 (silence) to 255 (full volume). However, only the truly righteous know that 
Sound Manager 3.0 added an even more powerful command for manipulating sound 
volume —volumeCmd. 
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The volumeCmd command does three things. First, like ampCmd, it allows you to 
scale the volume from silence to full volume. However, volumeCmd doesn’t stop 
there; like that revolutionary amplifier in the movie Spinal Tap that could go all the 
way to 11, it lets you go beyond full volume to overdrive the sound volume. And 
finally, it allows you to control the volume of the left and right channels 
independently, providing complete stereo control over your sounds. 

All this is possible because the volumeCmd command represents the sound volume 
in 16-bit fixed-point notation. By using the most significant 8 bits to represent the 
integer portion of the volume and the least significant 8 hits for the fractional 
portion, it provides very precise volume settings. And overdriving die sound is a 
cinch. By combining the left and right volume settings into one 32-bit quantity, 
volumeCmd gives you full control over how loud you can blast your speakers. 
Another command, getVolumeCmd, returns the current volume setting, in case you 
forgot what you set it to, 

A new interaction between the volumeCmd and ampCmd commands was 
added in Sound Manager 3.1. Previously, ampCmd would clobber the separate left 
and right settings made by volumeCmd, setting them to the same value. Storting with 
Sound Manager 3.1, volumeCmd now specifies a base volume for a channel, and 
ampCmd scales against that base, which lets ampCmd and volumeCmd coexist better 
when playing the system alert beep. * 

Table 1 gives some examples of values you can pass to volumeCmd and their effect. 
Remember, once you've changed the volume setting with volumeCmd, the setting 
is applied immediately to the current sound that’s playing (if any) and to every 
subsequent sound played on that channel. 


Table 1, Sample values for volumeCmd 


volumeCmd! 

Setting 

Right Channel 
Decimal Value 

Left Channel 
Decimal Value 

Effect 

0x01000100 

1.0 

1.0 

Full volume our both channels 
(the default) 

0x00000000 

0.0 

0.0 

Silence out both channels 

0x01000000 

1.0 

0.0 

Full volume out right channel; 
silence out left 

0x00000100 

0.0 

1.0 

Silence out right channel; full 
volume out left 

0x02000200 

2.0 

2,0 

Double the full volume out both 
channels 

0x01800040 

1.5 

0.25 

One and a half times full 
volume out right channel; one 
quarter out left 


The SoundSecrets sample program included on the CD demonstrates die usefulness 
of volumeCmd by providing a slider control to adjust left and right volume separately, 
with volume overdrive up to two times the normal hill volume. 


ACHIEVE PERFECT PITCH 

One of the trickiest things to do with the Sound Manager is to play a sound at just 
the right pitch. While the ffequencyCmd command lets you trigger a sound at a 
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given MIDI note value, and the rateCmd command gives you limited control over 
the pitch of the sound currently playing, before Sound Manager 3.3 there was no 
good way to just play a sound at an arbitrary pitch, short of generating the samples 
yourself. So Sound Manager 3.1 introduced the rateMultiplierCmd command, which 
gives you perfect pitch every time. 

The concept behind rateMultiplierCmd is very simple. Using a Fixed value, you can 
apply a multiplier to the playback rate of all sounds played on a channel. This allows 
you to vary the sample rate of die sound being played, and thus control its pitch, 

(Of course, changing the rate also changes the duration of the sound,) You can use 
getRateMultiplierCmd to return the current rate multiplier setting. 

Like any great concept, it’s most easily understood with an example, so Table 2 gives 
some values you can pass to rateMultiplierCmd and their effect. Remember, as with 
volumeCmd, once you change the rate multiplier with this command, the setting is 
applied immediately to the current sound that’s playing (if any) and to every 
subsequent sound played on that channel. Our helpful SoundSeerets application 
demonstrates the rateMultiplierCmd command with a slider control to adjust the 
playback rate of the sound from 0.0 to 2.0. 


Table 2* Sample values For rateMultiplierCmd 


rateM u Itipl i erC md 
Setting 

Decimal 

Value 

Effect 

0x00010000 

1.0 

Play sounds at the normal pitch setting (the default) 

0x00020000 

2.0 

Play sounds at a pitch shifted up one octave 

0x00008000 

0.5 

Play sounds at a pitch shifted down one octave 

0x00018000 

1.5 

Play sounds at a pitch shifted up half an octave 

0x00000000 

0.0 

Repeal the last audio sample Indefinitely, which 
effectively pauses playback on ihis channel 


PLAYING SOUND THE QUICKTIME WAY 

Something thai vexes nearly everyone using the Sound Manager is attempting to play 
contiminus sound. Many applications break sounds up into chunks as they’re read off 
the disk, and most games have background music that’s continuously generated and 
mixed with sound effects. After spelunking through Inside Macintosh: Sound, you’ll 
eventually come across the Snd I 1 ! ay Double Buffer routine, which looks like the 
answer to your prayers. I lowever, Snd Play Double B u ffe r has some serious limitations 
that you need to consider. 

First of all, SndPlayDoubleBtiffer ping-pongs between just two buffers, and the 
location of those buffers can’t be changed once the sound is started, which can be 
really inconvenient when you’re trying to piece together a lot of sound buffers off the 
disk. In addition, the format of die sound being played can’t be changed once the 
sound is started, and the headers describing the sound must be attached to the sound 
data itself. 

There has got be a better way, right? Well, QuickTime uses a strategy involving 
sound callbacks that’s much more flexible and doesn’t make you scratch your head 
over when to use that lastBuffer flag in SndPlayDoubleBuffer. Once you read about 
the QuickTime way you’ll probably want to use it too. 
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With the QuickTime strategy you trigger all your sounds with a plain old bufferCmd 
command, and set up callBackCmd to call you when that buffer is done playing. This 
has two big advantages: 

* Because bufferCmd takes a pointer to a sound header as its only parameter, 
you can queue up a different buffer for every callback if you want, freeing 
you from that pesky two-buffer limit. 

* Because the sound header records contain a pointer to die audio data, you 
have a lot more flexibility in buffer management, and you can dynamically 
adjust the buffer sizes to any values that make sense to you. 

This technique is demonstrated by Listing 4, taken from the Sound Secrets 
application on the CD. Basically, the interrupt routine just plays the next buffer anti 
then queues up a callback, which keeps the sound playing continuously. The 
application has a slider that lets you adjust the size of the buffer dynamically. 


Listing 4. Playing continuous sound 

// Issue bufferCmd to play the sound, using SndDoImmediate, 
sndCmd.cmd ~ bufferCmd; 
sndCmd.paraml = 0; 

sndCmd.param2 = (long) &globals->sndHeaderj 

err = SndDoImmediate(globals->sndChannel, ssndCtnd); 
if (err 1= noErr) 
return (err); 

jI Issue callBackCmd using SndDoCommand so that we get called back 

// when the buffer is done playing, 

sndCmd.cmd = callBackCmd; 

sndCmd.paraml = 0; 

sndCmd*param2 = (long) globals; 

err = SndDoCommand(globals->sndChannel, SsndCmd, true); 
if (err noErr) 
return (err); 


Remember, callBackCmd calls your application at interrupt time, so it’s up to you to 
set up your A 5 world if you want to use globals. You can't call Toolbox routines like 
those in the Memory Manager from within the callback; however, you can call most 
Sound Manager routines (see Inside Macintosh: Sound for information on individual 
routines). To make things easier, you can pass an application-defined value to the 
callback routine in param2 of callBackCmd. Also, to ensure correct queue processing, 
it's very important that you use SndDoImmediate to send bufferCmd, and 
SndDoCommand to send callBackCmd. 

COMPRESS WITH THE BEST 

While Sound Manager 3.0 included an architecture for decompressing arbitrary 
sounds (described in the article "Make Your Own Sound Components” in develop 
Issue 20), no method was provided to compress sounds. However, with the arrival of 
Sound Manager 3.1 and QuickTime 2.1, creating compressed sound files became as 
easy as opening a movie. 
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The compression technique demonstrated here uses the import/export facility built 
into QuickTime. Movie import components allow you to convert other files into 
QuickTime movies, while movie export components let you save QuickTime movies 
in other formats. QuickTime 2.1 provides an export component that works with 
Sound Manager 3.1 to let you save the audio in a QuickTime movie to an AIFF file in 
any format you please. 

QuickTime does tills by calling the Sound Manager to mix all the tracks together, 
converting them to the sample rate and size you specify, and even compressing the 
data with any of the compression algorithms provided by Sound Manager 3.1. The 
resulting AIFF file can then be played by any other Sound Manager routine, or 
converted back into a movie. The export component provides a dialog to let the user 
select die sample rate, sample size, and compression format of die AIFF file, as shown 
in Figure L 


Sound Export Options 


Compressor: [ 

IMfi 4:1 

3 




Rate: 

44.100 kHz 

la 


Size: OB bit <§>16 bit 
Use: O Mono ® Stereo 


ii o>: i 


Cancel 


Figure 1. Sound Export Options dialog 

Listing 5 demonstrates the process of converting a movie to an AIFF file, displaying 
the Sound Export Options dialog to let the user control the conversion process. The 
SetMoviePragressProc routine displays a progress dialog while the movie is being 
converted. The code is taken from ExportAIFF on this issue’s CD. 


Listing 5* Converting a movie to an AIFF file 

OSErr ConvertMovieToAIFF(F$Spec *inputFile, FSSpec *outpEtFile) 

short fRef; 

Movie theMovie; 

OSErr err ; 

err = OpenMovieFile(inputFile, &fKe£, fsRdPerm); 
if (err 1= noErr) 

goto OpenMovieFi1eFai1ed; 

err - NewMovieFromFile(&theMovie, fRef , nil, nil, 0, nil); 
if {err l- noErr) 

goto NewMovieFromFileFailed; 

(continued on next page) 
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Listing 5. Converting a movie to an AIFF file (continued] 

SetMovieProgressProcftheMovie, (MovieProgreasUPP) -1L, 0); 

err - ConvertMovieToFile(theMovie, nil r QutputFile, 1 AIFF', " sSixd', 
0, nil, showUserSettingsDialog, nil); 

DisposeMovie(theMovie); 

NewMovieFromFileFailed: 

CloseMovieFile(fRef}; 

OpenMovieFileFailed: 
return (err); 

} 


SOUNDING OFF 

Now that tills article has revealed some of the best-kept secrets of the Sound Manager, 
you can go out and create great applications on your own. Consider all your new 
skills — parsing and displaying sound resources, improving playback performance, 
adjusting volume and pitch, playing continuous sounds, and compressing audio. Now 
that the Sound Manager is your friend, you can focus on making your applications 
insanely great, instead of having the Sound Manager drive you insane! 


RELATED READING 

* Ins ide Mac in fos h: Soun d (Add i so n-We s I ey 1994) r 

* Macintosh Technical Note "GetCompressioninfoO" (SD 1). 

* "Make Your Own Sound Components" by Kip Olson, develop Issue 20, 
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BALANCE OF 
POWER 
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Profiling 


While this is sometimes true, a number of hurdles keep 
the PowerPC processors from completing even one 
instruction per cycle. These hurdles include instruction 
cache misses, data cache misses, and processor pipeline 
stalls. 

What may surprise you is how often die processor sits 
idle because of these hurdles. I did some tests and 
found that while opening new windows in one popular 
application, a PowerMacintosh 8500’s processor 
completed an average of only one instruction for every 
two cycles. This is not very efficient, considering its 
PowerPC 604 processor can complete up to four 
instructions per cycle. 


There’s little that compares to diving headfirst toward 
the ground at 120 miles per hour. I may have been 
going even taster when I last went skydiving. Tucking 
my arms in tightly, with my head back and legs even, I 
heard a deafening roar from the wind as I sped toward 
terminal velocity. “Terminal” would have been a good 
word for the situation if it weren’t for t he advances that 
have been made in parachute technology. 

Parachutes have come a long way since their debut, 
when they were billowy round disks of silk sewn with 
simple cords stretching to a harness. They were greatly 
improved when the square parachute was invented 
thirty years ago. The square parachutes look like an 
airplane’s wing, and they create lift in much the same 
way. Until recently, however, square parachutes weren’t 
improved upon much. Perhaps their superiority over 
round parachutes left everyone satiated. That lack of 
progress was unfortunate; if recent improvements — 
like many-celled parachutes and automatic activation 
devices — had been pursued many years ago, skydiving 
would be even safer today. 

The moral from this is to question satisfaction, and that 
will he our mantra for this column. In particular, I want 
you to question die performance gains you’ve seen by 
moving to native PowerPC code. In this column we’l) 
look at improved tools for examining PowerPC code 
performance, and you’ll see how such questioning can 
really enlighten you. 

ILLUSIONS 

The PowerPC processors can issue multiple instructions 
at once. You therefore may think they’ll tear through 
your code, executing many instructions per cycle. 


Much of that inefficiency is from instruction and data 
cache misses. As PowerPC processors reach faster 
dock rates, these cache misses will have an increasing 
impact. By minimizing cache misses we could realize 
a significant performance improvement. 

Simply recompiling your 680x0 code to native PowerPC 
code doesn’t typically generate efficient code. Many 
designs and data structures for the 680x0 architecture 
work very poorly when ported to PowerPC code. 

When you port native, you should carefully examine 
your code. Tuning for a cached RISC architecture is 
very different than for die 680x0 family Here are some 
important things to consider: 

* Redesign your data structures. Use long word-sized 
elements. Keep commonly used elements together, 
and keep everything aligned on double long word 
boundaries. 

* Keep results in local variables, instead of recomputing 
or calling subroutines to retrieve global variables. 

BETTER PROFILING 

Until recently you couldn’t measure cache misses unless 
you had a logic analyzer or other expensive hardware. 
The PowerPC 604 processor, however, includes an 
extremely useful performance measurement feature: 
two special registers (plus a register to control diem) 
that can count most events that occur in the processor. 
Each of these registers can count about 20 events, and 
there are five basic events that both registers can count. 

Here are just a few examples of w hat you can count 
with these registers: integer instructions that have 
completed; mispredicted branch instructions* data 


DAVE EVANS frkes to go skydiving when he can get away from 
his job gluing together the Mac OS software at Apple. He has gone 
a few times now, but hell always cherish the memory of his first 
[ump. Friends on the ground that day claim to have dearly heard 


his scream, although he was nearly a mile above them when he left 
the plane. On his second leap, if he hadn't opened the chute while 
upside down ond then watched it deploy through his legs, he might 
have noticed more of the surrounding countryside/ 
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cache misses; and floating-point instructions that have 
been issued. 

To use the performance profiling that die PowerPC 
604 processor provides, you’ll need to have one of the 
newer Macintosh models that include this processor, 
such as the PowerMacintosh 9500 or 8500, This will 
cost less than a logic analyzer yet allow you to get 
detailed performance profiles. 

Although these registers will show your software’s 
performance only on a 604-based Pow er Macintosh, 
your software’s cache usage and efficiency should he 
similar on other PowerPC processors. Use the 604’s 
special abilities to profile your code and you’ll benefit 
on all Power Macintosh models. 

For more accurate performance measurements, you 
may want to use the Emulator control panel, which is 
provided on this issue’s CD. With this control panel 
you can turn off die dynamic recompilation feature of 
the new emulator; this feaure, which is described in the 
Balance of Power column in Issue 23, can affect the 
performance of your tests over time. 

Also provided on the CD is Hie POWER Emulator control 
panel. This control panel lets you turn off the Mac OS support 
for R5/6000 POWER instructions and thus check for these 
instructions in your code (they'll cause a crash).* 

THE 4PM PERFORMANCE TOOL 

do use the new 604 performance registers, you don’t 
need to program in PowerPC assembly language. On 
this issue’s CD we’ve included a prototype application 
called 4PM. This tool, which was developed by engineer 
Tom Adams in Apple’s Performance Evaluation Group, 
uses the PowerPC 604-specific registers to provide 
various types of performance data. 

4PM is very simple to use. It presents three key menus: 
Control, Con fig, and Tests, as shown in Figure 1. You 
use these menus to select the type of performance 
measurement and an application you’d like to run the 


tests on. The application you’re testing is launched by 
4PM, and you can gather data either continuously or, 
using a “hot key,” exactly when you want. 

Once a test completes, 4PM fills a window with the 
results — a tabular summary with a different test run 
on each line. The Save command in the File menu will 
write the results to a file of type ’TEXT 1 . 

The Control menu. Use the Launch command in this 
menu to select an application and run it, gathering the 
test data specified with the Con fig or'Tests menu. 

The default configuration will measure cycles and 
instructions completed between when the application 
launches and when it quits. The Launch Again command 
simply relaunches the last application you tested. 

Check Use Hotkey if you’d like to control exactly when 
data is gathered. With this option, you start and stop 
collecting data by holding down die Command key 
while pressing die Power key. (This key combination is 
the same way to force entry to MacsBug, which you’ll 
be unable to do during the tests.) 

The Repeats command is just a shortcut that’s handy if 
you’re repeating a test multiple times. If you specify a 
repeat value with this command, your test application 
will be relaunched that many times after you quit it. 

The Intervals command allows you to collect data 
points at regular intervals; a dialog box offers the 
choices SO milliseconds, 100 milliseconds, 1 second, 
or Other, Normally just a total is collected, but by 
specifying an interval time you’ll instead receive a 
spreadsheet of timings. This will show what your code’s 
performance was as the test progressed. 

The Config menu. The commands in the Con fig 
menu allow you to tailor the test data by specifying 
exactly which events each register will count. The 
Count Select command lets you specify the machine 
states to collect data in; set this to “User Only” since 
you’ll be tuning application code. 


Control 

./Use Hotkey 

m 

Launch... 


Repeats... 


Launch Again 


y Internals... 




Tests 


Figure T • 4PM menus 
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The Tests menu. The commands in the Tests menu 
are for generating typical reports. Use the calibrate 
command to count the five basic events that are 
common to both 604 performance registers, including 
cycles and instructions completed; with this test 
selected, the Launch command will run your 
application five times, successively counting each of 
these events. You can use one of the remaining tests to 
collect more specific measurements. The caches, 
load/store, execution units, and special instructions 
tests each generate a report for the corresponding 
aspect of 604 performance. The Describe command 
displays a window describing which events are counted 
in the selected test. Use the New command to create 
your own tests. These new tests are automatically 
saved; you can use the Delete command to remove any 
that you’ve added. 

ASSEMBLY USAGE 

If you want finer results, you should read and write to 
the 604 performance registers directly This requires 
writing in PowerPC assembly language, but it allows 
you complete control over what data you 3 U collect for 
your time-critical code. 

You'll he accessing three new special-purpose registers: 
MMCRO, PMC I, and PMC2. MMCRO controls which 
events will be recorded and when exactly to record. 

The performance monitor counter registers, PMC1 
and PMC2, are the registers in which you’ll read the 
results. HI give a brief summary of how to use these 
registers, but you’ll need to read Chapter 9 of the 
PowerPC 604 RISC Microprocessor User's Manual for 
details. 

MMCRO is a 32-bit register that specifies all the 
options for performance measurement. Most of these 
options aren’t important to your application profiling, 
and you should at first leave the high 19 bits of 
MMCRO set to 0. The low 13 bits, however, specify 
which events you want counted in PMCl and PMC2. 
Bits 19 through 25 select PMC!, and bits 26 through 
31 select PMC2. See Chapter 9 of the 604 user’s 
manual to learn which specific bits to set. 

Here’s an example of how to measure data cache misses 
per instruction: 

.eq PMCl_InstructionsCompleted 2 « 6 

.eq PMC2_DataCacheMisses 6 

.eq MMCRQ_StopAllRecording $80000000 


li 

rO, MMCRO StopAllRecording 

mtspr 

MMCRO, rO ; stop all recording 

li 

r0, 0 

mtspr 

PMCl j rO ; zero PMC1 

mtspr 

PMC2, rO ; zero PMC2 

li 

rO, PMCl InstructionsCompleted + 
PMC2 DataCacheMisses 

mtspr 

MMCRO t rO ; start recording 


Notice that we load MMCRO with only the most 
significant bi t set to turn off all recording. This holds 
PMC1 and PMC2 at their current values and allows us 
to also zero PMC1 and PMC2 before we start recording. 
When you’re done measuring, follow with this code: 


li 

r 0, MMCR O S t opAlIRec o rding 

mtspr 

MMCRO, rO 

; stop all recording 

mfspr 

PMCl, r3 

; r3 is number of 



; instructions completed 

mf spr 

PMC2, r4 

; r4 is data cache misses 


Notice again that we turn off recording before reading 
the results. Otherwise the very act of reading the 
registers would affect the results; it will slow your code 
slightly, since the mtspr and mfepr instructions take 
multiple cycles to complete. 

Don’t record over very long periods of time, because 
the PM Cl and PMC2 registers can overflow. To measure 
over long periods, you should periodically read from 
the registers, add the result to a 64-bit number in 
memory, and dear the registers to prevent this overflow. 

Don’t ship any products that rely on these performance 
registers. They’re supported only in the current 604 
processor, and they’re not part of the PowerPC 
architecture specification. 

COMPLACENCY 

The moral is the same as for my tale of die square 
parachutes: question satisfaction. Don’t become 
complacent about the performance of your new native 
PowerPC applications. The profiling tools described 
here should help you more accurately measure and 
identify bottlenecks in your PowerPC code. Use that 
information to tune — especially paying attention to 
memory usage — and you’ll be surprised how much 
fester your product will run. Macintosh users 
consistently hunger for fester computers and more 
responsive software; spend some serious time tuning, 
and they’ll thank you for it. 


to Tom Adams, Geoff Chatterton, Mike Crawford; and 
Dove Lyons for reviewing this column. 
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Guidelines for Effective Alerts 


This article expands on the Macintosh Human Interface Guidelines 
for making attractive , helpful alerts (and dialogs) with a standard 
appearance and behavior. Standardization is important, because the 
more familiar an alert looks to users, the more easily they can concentrate 
on the message. Using the Finder as a source of good alerts, we provide 
examples of different alert types and discuss how to make alerts user- 
friendly. 



PAIGE K. PARSONS 


Alerts are an in-your-face way of getting the user's attention. It's hard for a user to 
ignore alerts because they block all other input to tine application until the user 
dismisses them. These little windows are powerful stuff. When used correctly, alerts 
are a helpful way to inform the user of a serious condition that requires immediate 
attention. When used incorrectly or capriciously, alerts are annoying and disruptive; 
since they must constantly be swatted out of the way, their content is often ignored. 

This article discusses when to use alerts, describes the different types of alerts, and 
gives tips for designing alert boxes. It elaborates and expands on alert guidelines in 
the Macintosh Human Interface Guidelines . At the end of the article, you're encouraged 
to try your hand at evaluating some real-life alerts. 

Though not implemented as such in the system, alert boxes are essentially a type of 
modal dialog box. This article focuses on alerts, but the guidelines can be applied to 
other dialog boxes as well. We specifically cover status dialogs here because diere are 
guidelines that are unique to that type of dialog. 


For information on implementing alerts and dialogs in your application, see 
Inside Macintosh; Macintosh Toolbox Essentials. * 


ALERTS IN GENERAL 

Alerts provide information about error conditions and warn users about potentially 
hazardous situations. They should be used only when the user's participation is 
essential; in all other cases, try using another mechanism to get your point across. For 
example, consider an error or output log if the messages are something that the user 
may want to save. 


PAIGE K. PARSONS (parsons@apple.com) is 
a Human interface Specialist at Apple. For two 
years she worked on the user interface of the 
Apple Dylan Development Environment. She 
recently began working at Apple's Human 
Interface Design Center, where she is responsible 


for software user interface issues in the PowerBook 
division. Favorite diversions include maintaining 
a Web site for the House Rabbit Society 
(http://www.psg Jcs. m it.edu/-cad/pa ige/HRS- 
home.him!] and trolling used record shops in 
Berkeley for vintage vinyl.* 
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The Macintosh Human Interface Guidelines haven 3 t caught up yet with the main 
recommendation in this article: that alerts be movable and application modal. The 
current interface guidelines and system software don’t allow alerts to be movable, but 
this may change in future versions of the Mac OS. Until then, you can implement 
your alerts as movable modal dialogs. 

Making alerts movable is helpful in case an alert is covering information on the screen 
that the user would like to see before responding to the alert. Another advantage to 
movable alerts is that they have a title, which gives the user a context for the error. 

Application modal means the alert is modal in the current application only: die user 
can’t interact with this application while the alert is on the screen, but can switch to 
another application. This is especially useful when the user needs to get information 
from another application in order to respond to the alert. (System modal, on the other 
hand, means the user can’t interact with the system ar all except within the alert box.) 

TYPES OF ALERTS 

Alerts come in three varieties, each of which is geared to a different situation. This 
section provides a few examples of each type, and also takes a look at status dialogs. 

NOW HEAR THIS: NOTE ALERTS 

A note alert simply conveys information, informing the user about a situation that has 
no drastic effects and requires no further action. For example, if a user selects a word 
and executes a spell check, an alert saying that the word is spelled correctly would be 
a note alert. Rather than provide a smorgasbord of options, a note alert contains a 
single button to dismiss the alert. 

Don’t use an alert to signify completion of a task; use alerts only for situations that 
require the user to acknowledge what has occurred. For example, the following note 
alerts are inappropriate and get in the user’s way: 

* The Trash has finished emptying, 

• The 3,432 files you selected have been copied. 

WATCH OUT! CAUTION ALERTS 

Caution alerts warn users of potentially dangerous or unexpected situations. You 
should use them, for example, to be sure the user wants to proceed with a task that 
might have undesirable results. In this case the alert normally contains only two 
buttons — one that cancels the operation and one that confirms it. Here are two 
caution alert messages: 

• An item named “READ ME” already exists in this location. Do you want to 
replace it with the one you’re moving? 

* The Trash contains t item. It uses 102K of disk space. Are you sure you want 
to permanently remove it? 

Don’t use alerts to confirm operations that would cause only a minor inconvenience if 
performed by mistake. Here are two examples of unnecessary caution alerts: 

* Do you really want to eject the disk “Installer”? 

• Do you really w ? ant to duplicate the selected item? 

Caution alerts are also used when an unexpected situation occurs and the user needs 
to decide w r hat to do next. The following examples contain only two buttons, for 
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canceling or confirming the operation, hut such an alert may present several choices 
if appropriate. 

• The document “Calendar” is locked, so you will not be able to save any 
changes. Do you want to open it anyway? 

* The item “Calendar” could not he deleted, because it contains items that are 
in use. Do you want to continue? 

Before deciding to use this type of alert, double-check to see if it’s really needed; 
superfluous alerts are a bad idea because users will get in the habit of dismissing alerts 
and possibly let an important one go by. It’s better to have a user make choices with 
commands instead of alerts. For example, the Finder has separate Shut Down and 
Restart commands (in its Special menu) instead of having only a Shut Down command 
with an alert asking “Restart after shutting down?” 

HOLD IT: STOP ALERTS 

Use a stop alert when calling attention to a serious problem that prevents an action 
from being completed. They typically have only one button, to dismiss the alert. 

Here are two good examples of stop alerts: 

• You cannot copy “Calendar” onto the shared disk “Zippy” because the disk is 
locked. 

• The alias “Calendar” could not be opened, because the original item could 
not he found. 

It’s especially important in stop alerts to give enough detail about the problem to help 
die user prevent it in die future. The following alert message doesn’t convey much 
useful information: 

* You cannot rename the item “Zowie”. 

This alternative is more helpful: 

* The name “Zowie” is already taken. Please use a different name. 

Similarly, if the chosen name is too long, it’s more helpful for the message to state the 
maximum number of characters a filename can have, 

EVERYTHING IS OK: STATUS DIALOGS 

Status dialogs inform the user when an application is busy and the user cannot 
continue working in the application until die operation finishes. In the Finder, these 
operations include copying, moving, and deleting files. Status dialogs should be 
displayed w henever the application is busy for more than about five seconds (unless 
posting and updating the dialog would take most of that time). During this time die 
application should also change the pointer to the standard wristwatch. 

A status dialog differs from an alert in that the user doesn’t need to explicitly dismiss 
the dialog; it goes away on its own once the task has completed. The dialog should 
contain a message that describes the status of the operation and a progress indicator 
to show how r much of the job has been completed. A status dialog may change 
messages depending on the stage of operation. Figure 1 shows a sta tus dialog at two 
stages of a copy operation. 

A sense of completion is important, so the application should be sure not to remove 
the status dialog until the progress indicator shows that the operation is done (such as 
by completely filling up the status bar in the example in Figure 1). 
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Preparing to copy... 

240 


Items remaining to be copied: 2 

Reading: NCSA Telnet 2.6.sea 


( stop ] 


■ 1 [ Stop | | 

Before copying 

During copying 


Figure 1* Stalus dialog during a copy operation 


ICONS IN ALERT BOXES 

Alert boxes always contain an icon that identifies the type of alert, as shown in Figure 
2. (Status dialogs contain no icon.) If you implement your alerts as movable modal 
dialogs, there's no Toolbox infrastructure set up for getting the correct icon 
automatically, so you'll need to remember which one to use. 




Note alert 


Caution alert 


Stop alert 


Figure 2. Icons for specific alert types 


A note on OpenDoc and alert icons: Open Doc part editors aren't as visible to 
the user as today's applications, but at times it may be important for users to make the 
connection between a running editor and its stored representation on disk. One such 
time is when the editor h reporting an error about itself such as an incompatible 
version; for these errors, the alert should contain the icon of the editor instead of a 
note, caution, or stop icon/ 


WRITING ALERT MESSAGES 

The alert message is the most important component of an alert. You want users to 
read and respond to your alerts easily and then continue smoothly with their work. 
This section gives tips on structure, content, tone, anti other important factors in 
writing effective alert messages* 

SITUATION, REASON, SOLUTION 

Every alert message should start by describing the situation that led to the alert, 
letting the user know what’s wrong. This is usually followed by the reason the 
problem occurred and a proposed solution to the problem. 

When describing the situation that caused an alert, be as specific as possible, to help 
the user understand the problem. 

Giving the reason the alert occurred is especially helpful when the application can't 
do something because it's dependent on some other operation that it can’t control. 
For example, compare these messages: 

* The abas “Wame” could not be opened. 

* The alias “Warne" could not be opened because the shared disk “Beatrix" 
could not be found on the network. 
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The first message doesn't give the user any information about why the problem 
occurred. Is the application that created the document missing? Is the file corrupted? 
The second message is much better because it tells the user why the operation could 
not be completed. 

Whenever possible* alerts should indicate a solution for the user. Users become 
extremely frustrated when an alert says something is wrong but doesn't offer a 
remedy to the problem. Even worse is an alert that tells the user something is wrong 
when the application could have fixed the problem itself The following would be a 
bad message because the Finder is capable of quitting all the applications on its own: 

* You must quit all running applications before shutting down your Macintosh. 

In cases where the application can perform the action itself, consider whether doing 
so may surprise the user; if so, presenting a caution alert may he more appropriate. 
For example, if the user attempts to shut down a Macintosh while other users have it 
mounted as a server, the Finder could just disconnect the other users automatically; 
however, in this case it’s more helpful to present an alert confirming die shutdown. 

BE CONSISTENT 

Be sure your alert messages are consistent in tone, content, and structure with each 
other as well as with other messages your software presents to die user. Are your 
application's alerts consistent with its status messages, for example? Do all your alerts 
refer to the application in a consistent manner? Users pick up on small inconsistencies, 
and even subtle differences can cause confusion. 

BE BRIEF 

Alert messages should be brief and to die point, to keep die user's attention. If you 
need to give a lot of information, consider writing it to an error log or providing a 
brief message in die alert along with a button to get to the application's help system. 

If you absolutely have to put a long message in an alert, keep in mind that many people 
have PowerBook computers or “classic” Macintosh computers with small screens. A 
good rule of thumb is that an alert message must consist of no more than 150 
characters to fit on a small screen. Also note that translation from English to other 
languages tends to expand the length of the message. Even translations into languages 
that use Roman characters can cause the message length to double or triple in size. 

BE ENCOURAGING 

Use a positive and constructive tone. After encountering a problem and being 
presented with an alert, the last thing the user wants is an overly negative response 
from the application. 

Avoid assigning blame or offending users. Don't accuse them of doing something 
wrong or stupid. Instead, give the reason an action cannot be performed, or offer to 
perform the action. Which message would you rather see? 

* You forgot to save your changes! 

* Save changes to access privileges for “Zippy”? 

PHRASING AND TERMINOLOGY 

Don't use double negatives, such as “No items are not used.” They're difficult for 
users to understand and just bad English. Double negatives can be especially 
confusing wEen combined with a Cancel button; the user rarely gets the expected 
outcome. 
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Keep the situation and action in the present* This is clearer and usually requires 
fewer words. For example, compare diese two messages: 

* An item named “READ ME” already existed in this location. Did you want 
to replace it with the one you moved? 

* An item named “READ ME” already exists in this location* Do you want to 
replace it with the one you’re moving? 

If there's an implied subject of a message, it should be the application* For example, if 
the user tries to open a document that the application can't open (as when it runs out 
of memory), the alert message might begin “Cannot open document*” Messages in 
which the user or some other noun could be the implied subject are more likely to be 
confusing — for example, “Have exceeded allotted network time. Try again later." 

Use terms that are familiar to the user. This often means avoiding computer jargon at 
all costs* Remember, terms that seem common to you may be unfamiliar to many 
Macintosh users* It depends on what type of user will lie working with your 
application. For example, the expression establishing a connection may be clearer than 
handshaking to many users* 

Use invalid instead of illegal. The user hasn’t broken die law, hut has simply given the 
application some information that it can’t handle* 

PUNCTUATION AND CAPITALIZATION 

Alert messages should always be complete sentences, beginning with a capital letter 
and ending with a period or question mark. The closing punctuation gives a sense of 
completion and lets the user know that the message hasn’t been truncated* 

Don’t use colons when requesting that die user supply information; instead, use a 
period. This makes your alerts consistent with other dialogs and user interface 
elements in the system software. 

Use an apostrophe ('), typed with Option-Shift-], rather than a single straight 
quotation mark Q, and use curly (“ ”) rather than straight (") double quotation marks 
— that is, Option-! an< J Option-Shift-[, rather than Shift-’* 

Use double quotation marks around any names in the message that are variable, such 
as names of documents, folders, and search strings* This lets the user know exactly 
what part of the message is the name* Remember that Macintosh filenames can 
contain spaces, which can make things really confusing without the quotes* Commas, 
periods, and other punctuation characters should be placed outside the quotation 
marks: 

* You cannot duplicate the shared disk “Warne”, because the disk is locked. 

Never use an exclamation point or all uppercase letters. It makes users feel as tf 
they're being shouted at, as in this example: 

* Revert to the saved version of “Map”? WARNING! All changes will be lost! 

STATUS MESSAGES 

In status dialogs, use an ellipsis (Option-semicolon, a character that looks like three 
periods) to indicate that an intermediate process is under way: 

* Preparing to copy... 

* vScanning “My Document”.. _ 
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For describing the status of a task, the terms canceled,failed, in progress , and complete 
are good choices. Avoid computer jargon such as aborted , killed , died , or ack’ed , 

ALERT TITLES 

Every movable alert should have an Informative title, to provide a context for the 
alert. Users may be working on several tasks at the same time and may not remember 
what action generated the alert. A well-chosen tide helps the user figure out not only 
which application caused the alert to appear, but also which action. 

The tide of the alert should be the same as, or closely related to, the command or 
action that generated the alert. (If the command has an ellipsis in it, don’t include the 
ellipsis in the alert title.) For example, when a user copies or duplicates an item in the 
Finder, the associated status dialog has the tide “Copy”; when the user chooses 
Empty Trash, the tide of the Finder’s status dialog is “Trash.” 

Like menu commands, alert tides are capitalized like book titles. Capitalize every 
word except articles (a, an, the), coordinating conjunctions (for example, and , or) 7 and 
prepositions of three or fewer characters (except when the preposition is part of a 
verb phrase, as in “Turn Off”). 

ALERT BUTTONS 

Alerts contain buttons that dismiss the alert or allow the user to make choices 
regarding how to proceed. The standard button height is 20 pixels. 

Try to limit die number of buttons that appear in an alert. The more buttons, the 
more difficult it is for the user to decide which is the “right” option. In addition, 
screen size often limits the number of buttons. As a general rule, about three buttons 
of ten or fewer characters will fit on a small screen. Burton names should be simple, 
concise, and unambiguous. 

Capitalize button names like book titles (for example, Connect to Server). Never 
capitalize all letters in the name (except for the OK button, which should always be 
named OK and never ok, Ok, Okay, okay, OKAY, or any other strange variation). 

On the Macintosh, ellipses are used after command names when the user needs to 
provide additional information to complete the command. An ellipsis after a button 
name indicates that the button leads to other dialogs, a rare but occasional 
occurrence. 

THE ACTION BUTTON 

Alert boxes that provide the user with a choice should be worded as a short question 
to which there is an unambiguous, affirmative response. The button for this 
affirmative response is called the action button. 

Whenever possible, label the action button with the action that it performs. Button 
names such as Save, Quit, or Erase Disk allow experienced users to click the correct 
button without reading the text of a familiar dialog. These labels are often clearer 
tlian words like OK or Yes. Phrase the question to match the action that the user is 
trying to perform. 

Tf the action can’t be condensed conveniently into a word or two, use OK. Also use 
OK when the alert is simply giving the user information without providing any 
choices. 
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THE CANCEL BUTTON 

Whenever possible, caution alerts should provide a button that allows the user to 
back out of the operation that caused the alert This button should be labeled 
“Cancel” so that users can easily identify the safe escape hatch. Cancel means 
“dismiss this operation with no side effects”; it doesn’t mean “done with the alert,” 
“stop no matter what,” or anything else. Pressing Comm and-period or die Escape 
key should have the same effect as clicking the Cancel button. 

Don't label the button Cancel when it's impossible to return to the state that existed 
before an operation began; instead, use Stop. Stop halts the operation before its 
normal completion, accepting the possible side effects. Stop may leave the results of 
partially completed tasks around, but Cancel never does. For example, a Cancel 
button would be inappropriate for a copy operation in which some of the items may 
have already been copied. Figure 1 (earlier in this article) illustrates using Stop in a 
status dialog for a copy operation. 

THE DEFAULT BUTTON 

The default button represents the action performed when the user presses the Return 
or Enter key. This button should perform the most likely action (if that can be 
determined). In most cases, this means completing the action that the user started, so 
the default button is usually die same as the action button. 

The default button's distinctive bold outline appears automatically around the 
default button in alerts, but remember that in dialog boxes you need to outline the 
button yourself.' 

If the most likely action is dangerous (for example, it erases the hard disk), the default 
should be a safe button, typically the Cancel button. If none of the choices are 
dangerous and there isn't a likely choice, there should be no default button; by 
requiring users to select a button explicitly, you protect them from accidentally 
damaging their work by pressing the Return or Enter key out of habit. 

POP QUIZ 

Now, for a bit of fun. I Ve been collecting some alerts that need improvement 
(Figures 3, 4, and 5). Based on the information in this article, can you find the flaws 
in each, and suggest improvements? 


Danger flier! B 
Redefining 2 kernel definitions: 


Incompatible function signatures mill cause 
pair O 

to replace the kernel definition 

pair (head, tail) -> new-pair :: <pair> 

CHUTION! Continuing the download may make the Runtime unusable! 


[ Continue J 


f^Cance^| 




Figure 3. Poorly designed "danger alert" 
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The public calendar seruer selected 
in the Chooser is different from the 
one you used last. If you change 
servers all public euent information 
stored in this document will be lost. 


[ Connect 


[[ luork offline 


Figure 4* * Poorly designed "server alert" 


fl successful capture has been performed. 
The “selected” area was sailed to a PICT file 
in the folder “Public” and was named “my 
picture”. Click to continue. 


Figure 5. Poorly designed "finished alert" 


The main problems with the alert in Figure 3 are as follows: 

* Its title isn’t descriptive (and is overly alarming). 

* 'The implied subject of the message is the user instead of the application. 

* The word “caution” is in all uppercase letters, and the punctuation includes 
an exclamation point. 

Also, the buttons are slightly shorter dian the standard height. Since the audience in 
this case is programmers, the words kernel and runtime are acceptable, though the use 
of runtime in this context is colloquial and can be more clearly stated with a simpler 
word. To improve this alert, you could change the title to “Download” and the 
message to “The code you are downloading redefines one or more kernel definitions. 
Continuing the download may make the application unusable.” Also, the buttons 
should be made 20 pixels high. 

The alert in Figure 4 isn’t movable, so it has no ride and can’t be repositioned. The 
message, with its “If..clause, isn’t direct and clear enough. Also, it’s not clear 
which button provides a safe escape mechanism. Finally, the “Work offline” button 
title has incorrect capitalization. To improve the alert, you could make it movable and 
give it the ride “Connect to Server.” The message should be “The public calendar 
server selected in the Chooser is different from the one you used last. Connecting to 
the new server will cause all public event information in your document to be lost.” 
You could add a Quit button as an escape mechanism, giving the alert three buttons 
— Quit, Connect, and Work Offline (the default). 

The alert in Figure 5 doesn’t contain any title, icon, or buttons. Because there are no 
buttons, it’s not clear how to get rid of the message without reading to the end of it. 
Also, its message should be stated in the present (for example, is named). But die 
biggest problem is that diis is a nuisance alert: the success of the capture could have 
been confirmed in an earlier step, when the user was asked to pick the filename. The 
solution is to get rid of the alert altogether. 
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THE PAYOFF 

Spending some time thinking about the design of your application's alerts makes 
sense because it results in a better product. If you follow the simple guidelines 
presented in this article* your alerts should be in really good shape. Your users will 
have an easier time recovering from errors, adding to their positive experience with 
your software. 


RECOMMENDED READING 

* Electronic Guide to Human interface Design [AddisorvWesley, 1994). This CD 
(available from APDA) combines the Macintosh Human Interface Guidelines and 
its companion CD, Making It Macintosh. 

* Macintosh Human Interface Guidelines , (Addison-Westey, 1993f Available 
separately from APDA in book form. 

* Inside Macintosh: Macintosh Toolbox Essentials (Addison-Wesley, 1992),, Chapter 
6, "Dialog Manager." 


Thanks to our technical reviewers Pete BickFord, 
Sharon Everson, Chris Forden, Elizabeth Mailer, 
and Mark Stern. * 


Macintosh Programmer's Toolbox Assistant 

V by Apple Computer, Inc. Have you ever needed to find current information about 

using a crucial Macintosh Toolbox call while in the middle 
of writing your application? Now with just a click of your 
mouse, you can get instant access to more than 5,000 
Toolbox colls that are at the heart of Macintosh system 
software. 

Macintosh Programmer's Toolbox Assistant is an 

invaluable CD-ROM database that will help you find key 
data structures, resources, constants, and functions when 
you need them the most. 

Available from a bookstore near you, or through APDA; 

1-800-282-2732 in the U.S. 1-800-637-0029 in Canada (716)871-6555 elsewhere 

For more information or product updates, see our site on the World Wide Web 
at http://www.info.apple.com/dev/mpta.html 
Updates also available on the develop Bookmark CD. 
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TIM MAHONEY 


MPW TIPS AND 
TRICKS 

ToolServer 
Caveats and 
Carping 


MPW comes with dozens of useful tools and scripts. 
They're handy for a lot of things besides programming 
— or would be, if you were willing to keep the MPW 
Shell open all the time, and if they weren't based on 
command lines. Fortunately, the Shell is not the 
only way to use them: a small application known as 
ToolServer makes it possible to run MPW commands 
in a standalone mode. You can write double-clickable 
MPW scripts, give MPW commands from AppleScript, 
and write front ends to tools in high-level programming 
languages. 

Using ToolServer isn't exactly like using the MPW 
Shell There are caveats if you want to write scripts and 
tools that will work in both environments. Well first 
take a look at these issues and then explore how to 
package commands for use wi th ToolServer 

MODULARITY AND FACTORING 

Shell scripting languages such as sh and csh in UNIX®, 
as well as MPW, have always taken a rather cavalier 
approach to code organization. Most configuration is 
achieved with a global namespace of environment 
variables. This is a problem with ToolServer, because 
you don’t want to load your entire set of MPW startup 
scripts every time you run a command. Even if you 
wanted to, you couldn't — ToolServer doesn't have 
text editing, menu bar customization, or other user 
interface elements of the MPW Shell, so it’s missing 
several built-in commands. Your existing startup 
scripts won't work, and some utility commands may 
also fail 

Three principles from structured software design are 
useful here: 


* Separate user interface code from core code. 

* Use the “include” mechanism to provide modularity. 

* Reduce dependencies between modules. 

Let's take a concrete example. Many of us cut our teeth 
as programmers on UNIX. Initiates of this brilliant but 
byzantine operating system tend to grow fond of its 
command set, in much the same way that cabalists 
become attached to bizarre metaphysical formulas 
purporting to explain the universe. A UNIX wizard's 
MPW startup script usually contains a list of aliases to 
translate between UNIX and MPW: Alias Is Files, Alias 
cp Duplicate, and so on. These commands are then 
used in all the wizard's utility scripts as well. This 
creates a problem with ToolServer: it can't use these 
startup scripts because they also customize the user 
interface with commands like AddMenu and SetKey. 
Without the aliases, though, the utility scripts won't run. 

One solution to this problem combines the first two 
principles listed above. First, separate die aliases from 
the user interface setup code, yielding two different 
startup files. Both files are invoked by the MPW Shell 
startup process but neither is invoked at ToolServer 
startup. Second, instead of assuming a particular global 
configuration, make each utility script explicitly include 
whatever setup files it may require. MPW's analog of 
the #include directive of C is Execute, which executes 
a file in the current namespace. 

We can apply common C bracketing conventions to 
avoid multiple inclusion of the same file. Assuming that 
our UNIX wizard has split off his or her aliases into a 
file named UNIXAliases, a script using these aliases 
would start — after the header comment — as follows: 

if {_UNIXALIASES_I -= 

execute UNIXAliases 

end 

The script file UNIXAliases would set the variable 

__UNIXALIASES_to something other than the 

empty string, and decline to execute itself again if it 
had already been executed, like so: 

if {_UNIXALIASES_} ~ *" 

set __UNIXALIASES__ "true" 

... # the aliases go here 
end # UNIXALIASES 


TIM M A RONEY was discovered on the Isle of Wig hi by seal 
farmers in the Year of Our Lord 1394, and again seventy years 
later by Tasmanian basket twirlers out for a stroll in the Yukon. The 
little tyke pursued a happy life of Fun, freedom, and quantum 


mechanics. He resurfaced m 1961, in the town of Holyoke, 
Massachusetts. Tim played a magician in bondage in a class play 
in the second grade, which may have prepared him For the 
contract work he's now doing at Apple.* 
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A different solution to the same problem involves the 
third principle, reducing dependencies between 
modules. Utility scripts don't really need to use csh 
commands, after all: the aliases are there mostly so that 
the wizard can type them into the MPW Shell, his or 
her fingers having long ago locked into an inflexible 
pattern of TTY interaction. If scripts don’t assume the 
availability of a different command set — that is, if they 
stick with the MPW command names — the aliases 
need not be included at all. 

Independence is a good idea for another reason: you 
may give your ToolServer scripts to other people at 
some point in your long and happy life. The more your 
commands depend on the global environment, 
including ToolServer startup files, the more likely they 
are to conflict with another user's environment. 

INPUT AND OUTPUT 

ToolServer implements most of the MPW Shell’s I/O 
system, which is based on the stdio library and UN1X- 
stylc redirection. However, it doesn't read keyboard 
input or display text output. All of its I/O channels are 
ultimately files, pipes, or the pseudodevice Dev:NulL 

The only mechanisms for interacting with the user in 
loolServer are commands like Alert and Confirm that 
display dialog boxes, and interface tools you write 
yourself. Even these must be used with caution, since 
loolServer can run remotely over a network, and 
hanging a server machine by bringing up a dialog box 
is often regarded as undesirable. 

It helps to separate user interface code from core code, 
as already discussed. Commands you intend to run w ith 
ToolServer should not have a user interface: they 
should perform an action that's completely specified by 
their command line. An outermost user interface script 
can present choices to the user, then invoke an innermost 
command that has no user interface. The outermost 
script is just for ToolServer; the imier script or tool is 
suitable for both ToolServer and the MPW Shell. 

You can detect when a command is running under 
ToolServer and squelch its user interface by looking at 
the environment variable BackgronndShell. This is die 
empty string when running under the MPW Shell, but 
it’s nonempty under ToolServer. Most user interactions 
i n MPW commands are just confirmation alerts, so 
if execution reaches a Confirm command and 
Backgrounds hell is set, assume that the user would 
answer “no.” All commands that require confirmation 
should support the -y and options, which provide 
answers on the command line, and these options should 
be provided when the commands are used from 
ToolServer. 


Some MPW commands, such as Make and Backup, 
write output to the Worksheet, and the user then 
selects and executes the output. This model doesn’t 
apply to the ToolServer environment since it has no 
Worksheet. The easiest solution is to redirect the 
command output to a temporary file, execute that file, 
and then delete it. This is less selective than using the 
Worksheet, which allows die user to decide which lines 
to execute. If selectivity is important, you can write a 
command that presents the lines of output to the user 
and allows them to be independently accepted or 
rejected. 

We don’t live in die best of all possible worlds, St. 
Thomas Aquinas and Dr. Pan gloss to the contrary, and 
so commands often return errors. These generate text 
that’s directed to the standard error channel. In the 
MPW Shell, error text goes to die ffontmost window 
by default, but in ToolServer, the default is a file named 
command.^rr in the folder containing the command file. 
This is very antisocial behavior, especially since 
commands invoke other commands and the error file 
could wind up buried at some arbitrary-seeming place 
in your folder tree. Redirect the standard error channel 
to save yourself from Sisyphean levels of frustration 
whenever something goes just a little bit wrong. 

There are two ways to redirect errors. First, you can 
use the standard MPW error redirection characters > 
>>, X, and XX m your outermost user interface script. 
For instance, die script line 

Veeblefetzer > "{Boot}"Veeblefetzer.Errors 

would redirect errors to the tile Veeblefetzer.Errors at 
the top level of your startup disk. This does little or 
nothing to bring the errors to your attention, though, 
so your outermost script should look something like 
this: 

Set ErrorFile "{TempFolder) "MyUti lity.Errors 
Delete -i “(ErrorFile)" 

Set Exit 0 # Don't bomb quietly on errors 
Potrzebie >> "{ErrorFile}" 
if {Status) == 0 

Veeblefetzer >> "{ErrorFile}" 

end 

if "Exists "(ErrorFile)"' 

Alert "Catenate "{ErrorFile} 

Delete "(ErrorFile)" 

end 

The other way to redirect errors is to set the ToolServer 
built-in variable BackgroundErr to the name of a file. 
This will create that file whenever there's an error. This 
is somewhat less flexible than redirection, but it can be 
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set once and for all in a ToolServer startup script. That 
would make the script above read like diis: 

Delete -i "{BackgroundErr}" 

Set Exit 0 # Don't bomb quietly on errors 
Potrzebie 
if {Status)- == 0 
Veeblefetzer 

end 

if "Exists *{BackgroundErr} 

Alert 'Catenate "{BackgroundErr)-"' 

Delete -1 "{BackgroundErr}* 

end 

Standard output can be controlled similarly, using 
either redirection characters or the environment 
variable BackgroundQut. 

FORMS OF TOOLS 

There are several ways to package commands for use 
with ToolServer. The most basic and boring ways are: 

* Use the Execute Script command in ToolServer’s 
File menu to select and execute a script file. 

* Drop a script file on the ToolServer application icon. 

* Give the “ToolServer [script ... ]” command in the 
MPW Shell. 

There are more interesting deployment modes, but 
they require a bit more explanation. 

Standalone scripts. If you change the creator of a 
script file to MPSX r , double-clicking it in the Finder 
will launch ToolServer and send it an Open Document 
event, causing it to be executed. Use this approach for 
your outermost user interface scripts. To change the 
creator, use MPW’s “SetFile -c "MPS X file” command. 

There is, alas, no such thing as a standalone tool, but 
you can write a one-line script that invokes a tool with 
any parameters or none. 

AppleScript. ToolServer is fully scriptable. Aside 
from the four required commands, it has only one 
scripting command, the dreaded DoScript. This takes 
a command written in another scripting language — 
MPW command language in this case — and passes 
the command to its script interpreter. DoScript is 
discouraged in new applications because it’s unstructured, 
but iris very useful for pre-AppleScript applications that 
have their own languages. 


A simple AppleScript script confers few benefits over 
a standalone ToolServer script. In fact, it’s better to 
avoid mixing scripting languages if you can. However, 
using FaeeSpan or another AppleScript authoring tool, 
you can use AppleScript to set up a conventional 
application that relies on ToolServer as a workhorse. 
Simply pass DoScript commands in response to user 
actions, redirecting errors and output to temporary files 
that you interpret in your AppleScript code. 

Apple events. Finally, you can take AppleScript one 
step further, driving ToolServer directly with Apple 
events generated from compiled software. This delivers 
the maximum in flexibility and performance. You could 
even write a project-file development system based 
on MPW compilers. Another possibility would be 
HyperCard XCMDs, allowing MPW commands to be 
invoked from HyperTalk. An Apple event front end 
could be created for a particular MPW tool, allowing it 
to be cleanly invoked from other scripts or compiled 
software; this might also provide a simple user interface 
for controlling it with dialogs and menus, 

ToolServer accepts the required Apple events, as well as 
DoScript and some special-purpose events related to 
status checking, command canceling, and error and 
output redirection. These are documented in Chapter 
4 of the ToolServer Reference manual that comes with 
MPW. In this column in the last issue of develop , I 
provided sample code for interacting with SourceServer 
(another Apple event-niriven MPW Shell subset), and 
that code can easily be adapted for ToolServer. 

TOOLS FOR THE FUTURE? 

Because it’s tied to a command-line interface, the 
MPW toolset has come to seem rather archaic, but 
there’s life in the old girl yet. ToolServer’s support for 
Apple events and AppleScript allows innumerable 
improvements in its interface. In the future, we may see 
friendly front ends for various MPW tools, as well as 
deeper support for compilation and other kinds of file 
processing with MPW tools in third-party development 
systems. 

Ultimately, MPWs command-line interface is destined 
to become a fading memory. Although it confers some 
advantages in power, it must give way to friendlier 
approaches in the end. However, if we fail to move i ts 
toolset forward into the post-command-line w-orld, we 
will be poorer for the loss. 


Thanks to Deeje Cooley Arno Gourdol, and Rick Mann for 
reviewing this column/ 3 
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Printing Images Faster With Data 
Compression 


Using JPEG image compression techniques can dramatically improve 
performance during printing to PostScript™ Level 2 printers; compressed 
images are significantly smaller and take much less time to print,. You 
don't need to write PostScript code or special-case your code for PostScript 
printing; QuickTime and the printer driver do most of the work for 
you. You don ’f have to wait to get started , either. If you implement 
JPEG image data compression techniques in your application , users 
printing to PostScript Level 2 printers with the current LaserWriter 
8.3 driver will see improvements in printing performance right away. 



DAVID GELPHMAN 


Many applications compress image data tor storage and transmission, but 
compressing images for [minting is relatively uncommon. With the techniques 
presented in this article, you can start printing with image data compression and 
realize significant performance gains without a lot of effort. First we’ll explore the 
concepts behind using image data compression for printing, and then go through 
three sample applications that show you how to do it. 

The first two samples demonstrate how to print existing compressed image data. 
Applications that already deal with JPEG compressed data, such as Web browsers 
and JPEG viewing applications, can benefit immediately from these techniques. 
Developers whose applications handle other kinds of compressed data (such as fax) 
can see how they might benefit in the future as printing software is enhanced to 
handle other types of compressed data. 


Some applications don’t already have compressed data to print. Painting applications, 
for example, handle image data that may not be in a standard compressed format. 
The third sample application shows you how to compress your data as you do your 
print-time imaging. 


To give you an idea of the performance gains you might expect with these techniques, 
I printed the same images with and without JPEG image data compression and 
compared print times and data sizes. The improvements are notable — compressed 
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color images, for example, can print in less than half the time. You may find the 
results so compelling that you’ll want to implement these techniques in your own 
application. 

This issue’s CD contains the sample applications as well as some images you can use 
with them. It also contains a prerelease version of LaserWriter 8.3.1, which you may 
find useful for testing your application as you implement printing with compression. 

THE BASICS 

Realistic images can be quite large, resulting in slow print times. Compression 
algorithms such as JPEG, fax, and LZW are used to reduce the size of these images 
for storage and transmission. Image data compressed in these formats can be 
decompressed on PostScript Level 2 printers. 

While many applications can handle compressed image data, at print time they 
usually decompress the data and use CopyBirs to draw the decompressed images. 
Only a few applications use custom PostScript code to take advantage of the image 
decompression available in PostScript Level 2 output devices, 

QuickTime’s Image Compression Manager provides an API for applications to 
compress and decompress still image data. By using the Image Compression Manager 
functions, applications can draw JPEG compressed image data. If this drawing takes 
place at print time, the application is effectively passing compressed image data to the 
printer driver; this allows the driver to handle the compressed data appropriately for 
the target output device, as described in the next section. The application doesn’t 
need to know whether that device is a QuickDraw, PostScript Level I, or PostScript 
Level 2 device. 

If your application handles only QuickDraw pictures, it doesn’t need to perform any 
special action to take advantage of image data compression. QuickDraw pictures 
containing JPEG compressed image data are available from various sources; 
QuickTime can compress QuickDraw pictures transparently and applications such as 
Adobe™ Photoshop can create QuickDraw pictures containing JPEG compressed 
image data. Applications that use DrawPieture to draw such pictures automatically 
take advantage of printer drivers that have special handling of compressed image data. 
All diey need to do is let the QuickDraw low-level drawing routines do their normal 
thing. 

LaserWriter drivers starting with version 8.3 are savvy about JPEG compressed 
images diat are drawn with QuickTime. When the driver receives data that’s 
compressed with JPEG compression and die PostScript output is destined for a 
PostScript Level 2 device, die driver sends the compressed data directly to the 
printer. Since JPEG compressed images can be as much as 1/10 to 1/40 the size of 
uncompressed images, the amount of data sent to the printer is much smaller, which 
drastically reduces print times. 

HOW THE PRINTER DRIVER HANDIES COMPRESSED IMAGE DATA 

In general, printer drivers intercept QuickDraw drawing through the QuickDraw 
low-level bottleneck routines. When an application draws compressed image data 
with die Image Compression Manager functions (or draws a compressed QuickDraw 
picture with DrawPieture), QuickTime passes the compressed data to the low-level 
QuickDraw drawing routines through the StdPix bottleneck routine. Normally 
StdPix decompresses the data and passes the decompressed data to the bitsProc 
bottleneck routine for drawing. 
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StdPix is described m detail in Inside Macintosh: QuickTime , pages 3-137 to 
3-139.* 


The LaserWriter 8.3 driver installs custom bottleneck routines as replacements for 
the standard bottlenecks, including bitsProc and StdPix. The custom StdPix 
bottleneck is key to the special handling of compressed image data, as shown in 
Figure L The driver installs the custom StdPix bottleneck in the printing graphics 
port so that it can intercept calls to StdPix and examine the compressed data. If the 
data is compressed with a compression type that the driver recognizes and knows the 
printer is capable of receiving, the driver sends the data directly to the printer. 
Otherwise, it calls the standard StdPix, which, as described above, sends the 
decompressed data to the bitsProc botdeneck. Drivers that don’t have a custom 
StdPix bottleneck (such as QuickDraw printer drivers and LaserWriter drivers 
previous to version 8.3) will always have decompressed data passed to their bitsProc 
bottleneck. 


Compressed 
image data 



Figure 1 * Special handling of compressed image data in fhe LaserWriter 8.3 driver 


Using a custom StdPix bottleneck lets a printer driver handle different compression 
types appropriately. It also allows for the generation of correct output both for 
PostScript Level 2 output devices, all of which support JPEG, fax, and L2W 
decompression, and for PostScript Level 1 devices, which don't support any 
decompression. For drivers like LaserWriter 8.3 that spool (for background printing 
or as part of foreground printing), there’s another advantage: since the spool file can 
contain compressed images instead of uncompressed images, users benefit from 
smaller disk space requirements. 

The techniques described here for handling compressed image data will work 
correctly with any printer driver, not just PostScript drivers with this special 
compressed image data handling* Of course, the performance benefits will be seen 
only with drivers that do have it. Most QuickDraw printer drivers will not gain a 
performance benefit because they ultimately render decompressed data on the host 
system and send the rendered results to the printer. In fact, if the data is being 
compressed on the host specifically for printing, there will a performance penalty, 

A few QuickDraw' drivers, such as Adobe's Acrobat™ PDFWriter, create data files 
that could potentially take advantage of image compression done by your application. 

Note that this technique of using a custom StdPix botdeneck applies to printing to a 
color graphics port on a Macintosh system that has Color QuickDraw built in (most 
do). Black-and-white ports don’t have StdPix bottlenecks; later we’ll look at what to 
do if you’re printing compressed data to a black-and-white port. 
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WHY THE DRIVER DOESN'T DO COMPRESSION FOR YOU 

You might be wondering: "(fusing image dara compression for printing is so great, 
why doesn't the driver do it for me automatically?" It's a good question and one that 
deserves a good answer 

Different kinds of images, such as fax images, photographic images, and synthetic 
images, have different characteristics. The best type of compression to apply depends 
on the type of image. Printer drivers operate at too low a level to make good 
decisions about image data compression. On the other hand, applications typically 
have a good idea about the kind of data they handle. 

Additionally, some compression algorithms, such as JPEG, can be “lossy" (that is, 
they throw away information), and it would be inappropriate for the driver to apply 
them without user control. The driver user interface isn’t well suited to specifying 
compression preferences, particularly since such decisions should be on a document 
by document basis or even on a per image basis within a document. The LaserWriter 
8.x drivers do use PackBits compression for all image data passed to their low-level 
bitsProc bottleneck, but that's the only active compression done by die drivers and it 
isn't very effecti ve for many types of image data. 

PRINTING EXISTING COMPRESSED IMAGE DATA THAT FITS 
IN MEMORY 

As mentioned earlier, applications that use DrawPicture to draw QuickDraw pictures 
containing JPEG data don’t need to do anything special to print the images. In this 
section well look at how applications can print compressed image data that is not in a 
QuickDraw picture. 

The JPEG Prin t sample application reads an existing compressed JPEG data file for 
display and printing. In this application, the JPEG data mnst fit completely in 
memory before it can be imaged. This is not a requirement for using compressed 
data, hut is the simplest approach to describe initially. Later well talk about the case 
where the data doesn’t all fit in memory at once. 

At application startup, the JPEG Print sample code checks that QuickTime is installed. 
The code also tests to make sure there’s a compression-decompress ion codec that can 
handle the decompression ofJPF.G data; the codec is used to decompress the data on 
the host if the data can't he sent to the printer in a compressed form. Applications 
that can already print compressed data without QuickTime and an appropriate codec 
should continue using their existing code to print when QuickTime and the codec 
aren’t present, 

FILLING IN THE IMAGEDESCR1PTION DATA STRUCTURE 

The QuickTime image decompression functions require a handle to an 
ImageDeseription data structure. This structure contains information about an 
image, such as the compression type used, the number of bytes in the compressed 
image, and the image height, width, and depth. Quicklime needs this data separate 
from the compressed data itself. 

In the case of JPEG compressed data, much of the information required in the 
LiiageDescription data structure is contained in the compressed JPEG data stream. 
The JPEG Print application reads the JPEG data stream and extracts the width, 
height, horizontal resolution, vertical resolution, and depth of the image. It then 
uses this data to build up an ImageDeseription structure for use with the Image 
Compression Manager functions. The specifics of parsing a JPEG data stream for 
image description information aren't discussed here; this part of the sample code 
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comes almost directly from the sample JFIF Translator application in the Macintosh 
OS Software Developer’s Kit, with little modification, 

CHOOSING THE APPROPRIATE DECOMPRESSION ROUTINE 

To draw compressed still images with QuickTime, you can use one of three functions: 
Decompress!mage, FDecompressImage, or the StdPix bottleneck routine. However, 
the Decompress!mage and FDecompressImage functions always call the standard 
StdPix bottleneck; they do not call any custom StdPix bottleneck (including 
LaserWriter 8’s) in the graphics port. Since we want our compressed image data to 
pass through the driver’s StdPix bottleneck, we’ll just call the StdPix bottleneck 
directly, as described in the next section. 

For drawing to a black-and-white port, you’ll need to use Decompresslmage or 
FDecompressImage since a black-and-white port doesn’t have a Std Pix bottleneck. 
One of the arguments to Decompresslmage and FDecompressImage (as specified 
in the QuickTime documentation) is a handle to the pixel map in which the 
decompressed image is to be displayed. Ln a black-and-white graphics port there is no 
PixMapHandle available; instead, there is a BitMap data structure. Decompresslmage 
and FDecompressImage am accept a BitMap instead of a PixMapHandle as the 
destination to draw to, and that’s what we pass to Decompresslmage when drawing 
to a black-and-white graphics port. 

CALLING THE STDPIX BOTTLENECK DIRECTLY 

The StdPix bottleneck is declared as follows: 

pascal void StdPix(PixMapPtr src, Rect *srcRect, HatrixRecordPtr matrix, 

short mode, RgnHandle mask, PixMapPtr matte, Rect *matteRect, short flags)? 

The first argument is a pointer to a PixMap “containing” the compressed image data. 
This isn’t a PixMap in the normal QuickDraw sense; instead, it’s a PixMap data 
structure that has compressed data “attached” to it with die QuickTime call 
SetCompressedPixMapinfo. This call associates an ImageDescription data structure 
and the corresponding compressed image data widi a PixMap data structure. It’s 
important that the compressed data not move in memory alter you’ve associated it 
with the PixMap. If you use a handle to your compressed data, as we do in the sample 
code, you should lock the handle before your call to SetCompressedPixMapInfo and 
keep it locked until after you’re done with the PixMap. 

'The next two arguments to StdPix specify a source rectangle and a transformation 
matrix that describes the mapping between die source rectangle of the image data and 
the destination rectangle. By specifying a source rectangle and a matrix rather than a 
source and a destination rectangle, the StdPix interface allows for more general 
coordinate transformations than just scaling and translation. Currently, however, 
Quicklime supports only scaling and translation. 

The mode argument specifies which QuickDraw transfer mode to use when drawing 
the image. JPEG Print uses the ditherCopy mode. When printing to PostScript 
printers, ditherCopy mode is treated by the LaserWriter 8.x driver exactly like 
srcCopv mode, and the PostScript interpreter does any halftoning or dithering 
appropriate for the PostScript output device. When imaging to QuickDraw output 
devices, ditherCopy causes QuickDraw' to dither the image, which usually yields 
better results than using srcCopy, 

StdPix also accepts mask and matte arguments to obtain special effects. The mask 
argument has the same effect as clipping to a mask region as part of the imaging call. 
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The matte arguments allow for effects similar to those of Color QuickDraw’s 
CopyDeepMask, Current LaserWriter 8.x drivers do not support clipping to bitmap 
regions, or the CopyDcepMask-like effects available with the matte arguments. 
Consequently, the mask and matte arguments are ignored by LaserWriter 8.x drivers. 

The final argument to StdPix is a flags parameter. The relevant flags are callOldBits 
and callStdBits; they work together to specify whether a call to StdPix results in a call 
to die bitsProc bottleneck with decompressed data. When the callOldBits and 
callStdBits flags are hodi set, StdPix will always call the bitsProc bottleneck with 
decompressed data. If callOldBits is set and callStdBits is not, StdPix will call the 
bitsProc bottleneck with the decompressed data only if the bitsProc bottleneck is not 
StdBits, but a custom bitsProc routine. 

The JPEG Print sample code uses a flags value of (callOldBits I callStdBits) to 
specify the most conservative handling of compressed image data during printing. 
Printer drivers that blow how to handle compressed image data, such as LaserWriter 
8.3, will have a custom StdPix bottleneck to intercept the call and adjust the flags 
appropriately Drivers that don’t blow how to handle compressed image data will 
always receive decompressed image data via their bitsProc bottleneck. 

Once we’re ready to call the StdPix bottleneck, we don't want to just call the function 
StdPix; instead, we must be careful to use any custom StdPix botdeneck that has been 
installed. To do tins, the code must check the current graphics port for custom 
QuickDraw bottlenecks, as shown in Listing 1. If there aren’t any the code gets the 
standard bottlenecks; otherwise, it gets the pointer to die CQDProcs record stored in 
the graphics port. Once it has the appropriate bottlenecks, the code uses the procedure 
pointer stored in die newProcl field of the CQDProcs record; this is the StdPix 
botdeneck. 


Listing 1 , Colling the QuickDraw StdPix bottleneck directly 

// Look to see if there are custom QuickDraw bottlenecks in the 
// current graphics port. 

if ((((CGrafPtr)qd.thePort)->grafProc5) == NULL) { 

// Get the standard bottleneck procs. 

SetStdCProcs(SmyStdProcs); 

// The newProcl field is the StdPix bottleneck« 

HyProcPtr = (StdPixProcPtr)myStdProcs*newProcl; 

} else { 

// Use the grafProcs record in the current port to obtain the custom 
// bottleneck procs* The newProcl field is the StdPix bottleneck, 
MyProcPtr = 

(StdPixProcPtr) ((CGra fPtr)qd * thePort)->grafProcs->newProc1; 

} 

// Now call the bottleneck. 

Calls tdP1xPr oc[MyP rocFtr, SpeciaIPixMapF, & s rcHect, & th eM a trix, 
ditherCopy, NULL, NULL, NULL, flags); 


USING DATA-LOADING TECHNIQUES TO PRINT LARGE 
COMPRESSED IMAGES 

The compressed image data you’re working with may not fit completely in memory, 
QuickTime supports this case through the use of a data-loading function, which you 
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supply, QuickTime calls this function as needed to obtain data during image 
decompression. Data loading eliminates the need to have the full image in memory, 
greatly reducing memory usage. 

The use of a datadoading function is described in somewhat sketchy terms in Inside 
Macintosh: QuickTime, pages 3-148 to 3-150- Basically, your application creates a 
buffer that your datadoading function uses for passing data to QuickTime, In 
preparation for the StdPix call, you call SetCompressedPixMapInfo with a pointer 
to the beginning of the buffer, the buffer length, and your datadoading function. 
When you call the StdPix bottleneck, QuickTime calls the datadoading function as 
necessary to obtain the compressed image data. 

The datadoading function is declared as follows: 

pascal GSErr MyDataloadingProc(Ptr *dataP, long bytesNeeded, long refcon); 

The first argument is a pointer to a pointer into your data buffer (the one you supplied 
in the call to SetCornpressedPixMapInfo as described earlier). The bytesNeeded 
argument tells your function how many bytes need to be available in the data buffer 
pointed to by the pointer in *dataP after the function call returns. The refcon 
argument lets you pass additional information to your datadoading function* 

EXTENDING JPEG PRINT WITH A DATA-LOADING FUNCTION 

The sample application JPEG Print with Dataload, an extended version of JPEG 
Print, uses the function MyDataLoadingProc, shown in Listing 2* Code not included 
here fills up the buffer with the first chunk of compressed data and sets up the data- 
loading function so that the refcon passed to it is a pointer to our application-defined 
DataLoad structure. 

The datadoading function’s job is to ensure that when it’s called with a request for 
bytesNeeded bytes of data, ai least that many bytes are available in the buffer pointed 
to by *dataP after the datadoading function returns. When MyDataLoadingProc is 
called with dataP not NULL, the code first computes how many bytes remain in the 
buffer from *dataP to the end of the buffer. If that number of bytes is greater than or 
equal to bytesNeeded, there are enough bytes available and the function returns. 
Otherwise, the data from *dataP to the end of the buffer is copied to the beginning of 
the buffer, and the remainder of the buffer is filled up with new data. Once the buffer 
is refilled, *dataP is set to point to the beginning of the buffer so that the caller starts 
getting its data there, 

TECHNIQUES FOR COMPRESSING AND PRINTING 
UNCOMPRESSED DATA 

Your application may not have compressed data to print. The third sample application 
on this issue’s CD, PrintPICTtoJPEG, compresses 32-bit-deep image data and prints 
it. To obtain a source of bits to compress, PrintPICTtoJPEG takes a PICT file and 
images it into a 32-bit-deep offscreen bitmap. It then draws from this bitmap into the 
current graphics port. During printing, the data in the offscreen bitmap is (optionally) 
compressed using JPEG compression, and then printed using the techniques for 
printing compressed data as discussed above for the JPEG Print application. 

The PrintPICTtoJPEG application uses PICT data solely as a source of bits to use 
to demonstrate compression. By no means are we advocating this technique as the 
proper way to print QuickDraw pictures* QuickDraw pictures may contain line art, 
text, custom PostScript code, and images of varying depths that will image and print 
much better if you just use DrawPicture. A good portion of die PrintPICTtoJPEG 
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Listing 2. The data-loading function 

static pascal OSErr MyDataLoadingProc(Ftr *dataF, long bytesNeeded, 
long refcon) 

{ 

OSErr theErr = noErr; 


if (dataP NULL) { 

DataLoadPtr theDataLoadPtr = (DataLoadPtr) refcon? 

// refcon is a pointer to a structure that contains the locked 
// handle to our buffer, a field with the buffer size, and a field 
// with the file reference number of the image data file we are 
// decompressing. 

Ptr theDataBufferP = 

StripAddress(*(theDataLoadPtr->theDataBufferH)}; 
long theBufferSize = theDataLoadPtr->theBufferSize; 
short theRefNum = theDataLoadPtr->theRefNum; 


// Calculate the number of bytes left in our existing data buffer, 
long bytesAvail = theBufferSize - (*dataP - theDataBufferP); 


// Are there enough bytes in our buffer for this call? If so, we 
// don't need to read any more data, 
if (bytesNeeded > bytesAvail) { 

//We don't have enough bytes of data in our buffer. Figure 
// out how many bytes we should read to refill the buffer, 
long bytesToRead = theBufferSize - bytesAvail; 


// If there are bytes available at the end of our buffer, move 
// them to the beginning of the buffer, 

if (bytesAvail) BlockMove(*dataP, theDataBufferP, bytesAvail); 


//Go ahead and fill up the rest of the buffer, starting just 
// after the last valid byte in the buffer, 
theErr = FSRead(theRefNum, sbytesToRead, theDataBufferP + 
bytesAvail); 

// Ignore end of file errors, 
if (theErr == eofErr) theErr = noErr; 


// Reset the data pointer used by the caller of the data- 
// loading function so that it points to the first byte of 
// valid data, which is now at the beginning of our buffer, 
*dataF » theDataBufferP; 

} 

} else { 

// The data mark reset case. This implementation doesn't know how 
// to reset the stream, so we return an error. We haven't seen 
// a data mark reset as part of JPEG decoding, {Note that not 
// handling this case slows down PhotoCD significantly,) 
theErr = -1; 

> 

return theErr; 
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application is devoted to getting a QuickDraw picture and drawing it into the offscreen 
bitmap as a source of bits. The interesting part of the application is the compression 
and imaging of the bits once we have them, and that’s what we’ll discuss here. 

The PrintPICTtoJPEG application compresses data only as part of printing it. Of 
course, it isn’t necessarily true that you would compress data only during printing; it’s 
very likely that you would maintain the data in a compressed form* Only you know 
for sure how you want to handle it. 

PrintPICTtoJPEG also does image compression on the data only if the printing port 
is a color graphics port; otherwise, it just does the usual Copy Bits* (If you already 
have compressed image data, you cun use FDeeompressImage as in the JPEG Print 
application to draw already compressed images to a black-and-white graphics port. 

If you’re compressing strictly for printing, there’s no obvious benefit to do so for a 
black-and-white port.) 

USING COMPRESSIMAGE 

The simplest way to compress image data is to use the QuickTime functions 
Compress Image and FCompressImage. You call GetMaxCompressionSize to 
determine the maximum compression size of your image, and then allocate a handle 
of that size and pass it to Comprcsslmage or FCompressImage, as shown in Listing 3 . 

GetMaxCompressionSize is likely to return a large size for full color images, perhaps 
a larger amount of memory than the application can allocate out of its application 
heap. To allow for this, PrintPICTtoJPEG first tries to allocate a handle in its 
application heap by using NewHandle. If that fails, it attempts to allocate temporary 
memory using the TempNewHandle function. In this way, the application can compress 
images when temporary memory is available without requiring a large application 
heap. If there isn’t enough memory available, you can use the FCompressImage 
function with an application-supplied dat %-unhading function to write the data to 
disk as it’s being compressed by QuickTime. 

The sample code directly chooses JPEG image compression with any codec that 
supports JPEG compression with a quality value of cod ecN o rma 1 Qua! ity, Hie other 
available constants for compression quality values are codecLosslessQuality, 
codecMaxQuality, codecMinQuality, codecLowQualily, and codecl lIghQuality. 
These constants give varying compression ratios and corresponding image fidelity. 

PROVIDING A USER INTERFACE FOR COMPRESSION PREFERENCES 

Although PrintPICTtoJPEG doesn’t do this, your application should provide the 
user a way to specify compression parameters when using JPEG compression* This 
is especially important when you’re applying a lossy compression method such as 
JPEG, since there’s a tradeoff between compression size and image fidelity. Such a 
decision is appropriate on a per document or even a per image basis. 

The PrintPICTtoJPEG application knows that the data it’s w orking w ith is best suited 
for JPEG compression. If your application has a good idea oi what kind of image data 
it’s working with, it can make the choice of which compression scheme to apply to the 
data. If not, you should probably use the standard image-compression dialog to let 
the user choose both the compression scheme and the compression parameters. 

PERFORMANCE MEASUREMENTS 

As part of developing the sample applications, I did some stopwatch time measurements 
to see what kind of performance improvements we’d get with JPEG image data 
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listing 3* Compressing image data with Compresslmage 
CodeeType theCodecType = 'jpeg 1 ? 

CodecComponent theCodec = (CodecComponent) anyCodec; 

CodecQ spatialQuality = codecNormalQuality; 
short depth = 32; 

// sFixWap is a handle to the pixel map to be compressed, 

// bounds is a pointer to a rectangle specifying the portion of the 
// image to compress, 
if (theErr “ noErr) 

theErr - GetMaxCompressionSizefsPixMap, bounds, depth, 

spatiaIQuality, theCodecType, theCodec f SmaxCompressionSize ); 
if (theErr -= noErr] { 

// This allocation should be no problem. 
theDescH * 

(ImageDescriptionHandle) NewHandle(sizeof(ImageDescriptionHandle)); 
// This allocation is probably for a lot of memory* 
compressedDataH * NewHandle(maxCompressionSize); 
theErr - MemError{); 

// See if we allocated the ImageDescriptionHandle but not the memory 
//to receive the compressed image, 
if ((theDescH != NULL) && (theErr J* noErr)) { 

// See if we can get temporary memory instead. Since we're going 
// to use the temporary memory as a real handle, we require 
// System 7-0 or later. 

compressedDataH = TempNewHandlelmaxCompressionSize, frtheErr); 

// This probably can't happen, but just in case... 
if (compressedDataH == NULL && theErr =- noErr) 
theErr = iMemFullErr; 

> 

> 

if ((theErr == noErr) && (compressedDataH J = NULL) 

&& (theDescH 1= NULL)) ( 

MoveHHi(compressedDataH); 

HLoc k(comp re s s e dDataE); 

theErr = Compresslmage(sPixMap, bounds, spatialQuality, theCodecType, 
theDescH, StripAddres s(*compressedDataH)); 

HUnlock(compressedDataH); 


compression. (The image files I used are included on this issue's CD.) The results, 
while carefully obtained, are obviously not comprehensive, but they'll give you an 
idea of what you can expect. All measurements were taken using a PowerMacintosh 
6100/66 as the computing host on relatively unloaded LocalTalk and EtherTalk 
networks. Unless the application uses JPEG image compression, the LaserWriter 83 
driver compresses the data using PackBits compression. 

For comparison purposes, I used LaserWriter 83, which has the special support for 
JPEG images described in this article, and Laser Wri ter 83.2, which does not. In both 
eases, the application printing code was identical. LaserWriter 8.3 sends the compressed 
JPEG data directly to a PostScript Level 2 printer; w T ith LaserWriter 8.2.2, the data is 
decompressed on the host Macintosh by QuickTime and passed to the driver's 
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bitsProc bottleneck. Since the LaserWriter 8.2,2 driver is seeing uncompressed data, 
it compresses the data with PackBits compression before sending it to the printer. 

To measure print times for already existing compressed data, I used the JPEG Print 
application to take an already compressed 186K JPEG image of a jaguar and print it 
to a PostScript Level 2 printer. Table 1 shows the results. 


Table 1. Jaguar JPEG image print times for already compressed data 


Printer 


Print Time/ 

Network PackBits 


Print TifTie r 
JPEG 


LaserWriter 320 LocalTalk 

LaserWriter 16/600 EtherTalk 


289 seconds 1 25 seconds 

121 seconds 42 seconds 


Next I used the PrintPICTtoJPEG sample application to measure and compare 
printing times both with and without compression on the host (Table 2). I used the 
same jaguar image as before but saved as a PICT file, and a smaller PICT file I already 
had on hand. Doing image compression on the host is time intensive: it routinely took 
2 to 4 seconds to compress the large jaguar image. Even so, overall performance is 
better because the data transfer times to the printer are so much smaller. 


Table 2. PICT 

image print times when compressing data on the 

Print Time, 

host 

Print Time, JPEG 

Image File 

Printer 

Network 

PackBits 

Normal Quality 

Jaguar 

LaserWriter 320 

LocalTalk 

288 seconds 

129 seconds 

[as PICT) 

LaserWriter 16/600 

EtherTalk 

1 16 seconds 

44 seconds 

Portrait pict 

LaserWriter 320 
LaserWriter 16/600 

LocalTalk 

EtherTalk 

54 seconds 

22 seconds 

37 seconds 

1 8 seconds 


Table 3 compares the data sizes for JPEG and PackBits compression. 


Table 3. Image compression data sizes 


Image File 

Jaguar 
Portrait.p id 


Image Size, 
PackBits 

2955K bytes 
399K bytes 


Image Size, JPEG 
Normal Quality 

186K bytes 
44 K bytes 


PRINTING WITH DATA COMPRESSION: CURRENT AND 
FUTURE DRIVERS 

loday’s LaserWriter 8.3 driver has direct support for handling JPEG compressed 
images as described in this article. LaserWriter 8.3 supports JPEG compression only 
when printing to Apple’s PostScript Level 2 printers. When printing to other 
PostScript printers or to PostScript files on disk, the driver uses the JPEG 
decompressor on the host to decompress the data, regardless of user settings. 
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LaserWriter 8.3.1 and future LaserWriter 8.x drivers will take advantage of JPEG 
compression when printing to all PostScript Level 2 printers as well as when saving 
to disk with Level 2 Only selected in the standard file dialog. Adobe’s PostScript 
printer driver for the Macintosh, PSPrinter, will soon take advantage of JPEG 
compression, as will a future version of the PostScript printing system for 
QuickDraw GX. 

The prerelease version of LaserWriter 8.3.1 on this issue’s CD will enable you to test 
your application with JPEG compression when printing to non-Appfe printers or to 
disk. Remember that JPEG compressed data will be written into the data stream only 
when your application prints JPEG compressed data and the printer is a PostScript 
Level 2 printer. If you’re saving PostScript files to disk, be sure to choose the Level 2 
Only setting in the standard file dialog. Choosing the Level 1 Compatible setting 
causes the driver to wTite uncompressed data into the output file. When you print 
24-bit photo-realistic images using JPEG compression, files saved with the Level 1 
Compatible setting will be about 10 to 40 times larger than files saved with the Level 
2 Only setting. 

Since PostScript Level 2 output devices also have fax and LZW decompression filters 
available, Apple is considering adding support for these compression formats to a 
future LaserWriter 8.x driver so that applications handling these types of data can 
take advantage of the techniques described here. If you would take advantage of fax or 
LZW support in the LaserWriter driver, let us know at AppleLink DEVFEEDBACK 
or devfeedback@applelink.apple.com on the Internet. 

LET'S GET STARTED! 

JPEG images are now abundant, especially on the Internet where more and more 
people encounter them each day. Let’s start printing these as compressed images! 

By implementing the techniques presented here for printing JPEG compressed 
image data, you can give your users immediate and substantial gains in printing 
performance. Plus you’ll he well on your way to printing other kinds of compressed 
data wdien printing software is enhanced to support it. 


Thanks Jo Richard Blanchard, Paul Danbold, 
Peler Hoddie, Kent Sandvik, and Nick Thompson 
for reviewing ihis article,* 
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The New Device Drivers: Memory Matters 


If you're writing a device driver for the new PCI-based Macintosh 
computers, you need to understand the relationship of the memory an 
application sees to the memory the hardware device sees. The support 
for these drivers (which will also run under Copland , the next 
generation of the Mac OS) includes the PrepareMemoryForl O 
function , as discussed in my article in Issue 22. This single coherent 
facility connects the application's logical view of memory to the 
hardware device's physical view. PrepareMemoryForlO has proven 
difficult to understand.; this ankle should help clarify its use. 


If you managed to struggle through my article “Creating PCI Device Drivers* in 
develop Issue 22, you probably noticed that it got rather vague toward the end when 1 
tried to describe how the PrepareMemoryForlO function works. There are a few 
reasons for this: the article was getting pretty long and significantly overdue (the 
excuse), and I really didn’t understand the function that well myself (the reason). 
Things are a bit better now, thanks to the enforced boredom of a very long trip, the 
need to teach this algorithm to a group of developers, and some related work Pin 
doing on the SCSI interface lor Copland, 

My previous article showed die simple process of preparing a permanent data area 
that might be used by a device driver to share microcode nr other permanent 
information with a device. 'This article attacks a number of more complex problems 
that appear when a device performs direct memory access (DMA) transfers to or from a 
user data area. It also explores issues that arise if data transfers are needed in 
situations where the device’s hardware cannot use DMA. 

A later version of die sample device driver that accompanied the Issue 22 article is 
included in its entirety on tills issue’s CD. Of course, you’ll need a hardware device to 
use the driver and updated headers and libraries to recompile it. Included is the source 
code for the DMA support library 1 (files DM Alfa ns fere and DMATransfer.h), which 
consists of several functions I 've written that interact with PrepareMemoryForlO; the 
revised sample device driver shows how this library can be incorporated into a 
complete device driver for PCI-based Power Macintosh computers. 

Til assume that you’ve read my earlier article (which you can find on the CD if you 
don’t have it in print)* That article gives an overview of die new device driver 
architecture and touches on the PrepareMemoryForlO function, but for a 


MARTIN MINOW is writing the SCSI plug-in For who is more cynical about Apple management. 
Copland on a computer named There must be a During the few moments he can escape from 

pony here" and competes with his boss to see meetings, he runs with the Hash House Harriers. * 
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comprehensive description of the architecture and details about the function, see 
Designing PCI Cards and Drivers for Power Macintosh Computers (available from 
APDA). I’ll also assume that you 1 re reasonably familiar with the basic concepts of a 
virtual memory operating system, including memory pages and logical and physical 
addresses; for a brief review, see “Virtual Memory on the Macintosh.” 

PREPARING MEMORY FOR A USER DATA TRANSFER 

At the beginning of a user data transfer (a data transfer on behalf of a program that's 
calling into your driver), die device driver calls PrepareMemoryForlO to determine 
the physical addresses of the data and to ensure the coherency of memory caches. At 
the end of the transfer, the driver calls the CheckpointJO function to release system 
resources and adjust caches, if necessary. PrepareMemoryForlO performs three 
functions that are necessary for DMA transfers: it locates data in physical memory; it 
ensures that the data locations contain die actual data needed or provided by the 
device; and, with the help of CheckpointlO, it maintains cache coherence. 

Your device driver can call PrepareMemoryForlO from task level, from a software 
interrupt, or from the mainline driver function (that is, DoDriverlQ). CheckpointlO 
can be called from task level, from a software interrupt, or from a secondary interrupt 
handler. (For more on the available levels of execution, see “Execution Levels for 
Code on the PCI-Based Macintosh.”) In a short while, well see how the fact that 
these functions must be called from particular points affects the transfer process. 

If the data is currently in physical memory, PrepareMemoryForlO locks the memory 
page containing the data so that it cannot he relocated. If the data isn't in physical 


VIRTUAL MEMORY ON THE MACINTOSH 

BY DAVE SMITH 


Virtual memory on the Macintosh has two major functions: 
it increases the apparent size of RAM transparently by 
moving data back and forth from a disk file, and it remaps 
addresses. Of the two, remapping addresses is more 
relevant to device driver developers (and, incidentally, 
much more of a headache). 

When Macintosh virtual memory is turned on, the 
processor and the code running on the processor always 
access /ogica/ addresses. A logical address is used the 
same way as a physical address; however, the Memory 
Management Unit (MMU) integrated into the processor 
remaps the logical address on the fly to a physical 
address if the data is resident in memory. If the data isn't 
resident in memory, a page fault occurs; this requires 
reading the desired data into memory from the disk and 
possibly writing other, unneeded data from memory to the 
disk to free up space in memory, [This explanation is 
slightly simplified, of course.) 

Since it would be impractical to have a mopping for each 
byte address, memory is subdivided into blocks called 
pages, A page is the smallest unit that can be remapped. 
Memory is broken into pages on page boundaries , which 


are page-size intervals starting at 0. The remapping allows 
physical pages that are not actually contiguous in physical 
memory to appear contiguous in the logical address space. 

The Macintosh currently uses a page size of 4096 bytes; 
however, future hardware may use a different page size. 
You should call the GetLogicalPageSize function in the 
Driver Services Library to determine the page size if you 
need it. 

DMA is performed on physical addresses since the MMU 
of the processor is not on the address bus that devices 
use. One of the functions of PrepareMemoryForlO is to 
translate logical addresses into physical addresses so that 
devices can copy data directly to and from the appropriate 
buffers. 

Many virtual memory systems provide multiple logical 
address spaces to prevent applications from interfering 
with each other. It appears to each application that it has 
its own memory system, not shored with any other 
application. The Macintosh currently has only one logical 
address space, but future releases of the Mac OS will 
support multiple logical address spaces. 
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memory, PrepareMemoryForlO calls the virtual memory subsystem and a page fault 
occurs, reorganizing physical memory to make space in it for the data. After the 
transfer finishes, CheekpointfO releases the memory page locks* 

PrepareMemoryForlO and CheekpointfO perform an important function related to 
the use of caches* A cache is a private, very fast memory area that the CPU can access 
at full speed* The processor runs much faster than its memory runs; to keep the 
processor running at its best speed, the CPU copies data from main memory to a 
cache. Both the PowerPC and the Motorola 68040 processors support caching, 
although their implementation details differ. The important point is that a value of a 
data item in memory can differ from the value for the same data item in the cache 


EXECUTION LEVELS FOR CODE ON THE PCI-BASED MACINTOSH 

BY TOM SAUtPAUGH 


Native code on PCI-based Macintosh computers may run 
in any of four execution contexts: software interrupt, 
secondary interrupt, primary interrupt, or task. All driver 
code contexts have access to a driver's global data. No 
special work (such as calling the SetA5 function on any of 
the 680x0 processors) is needed to access globals from 
any of these contexts. 

SOFTWARE INTERRUPT 

A software interrupt routine runs within the execution 
environment of a particular task* Running a software 
interrupt routine in a task is like forcing the task to call a 
specific subroutine asynchronously When the software 
interrupt routine exits, the task resumes its activities* A 
software interrupt routine affects only the task in which it's 
run; the task can still be preempted so that other tasks can 
run. Those tasks, tn turn, can run their own software 
interrupt routines, and a task running a software interrupt 
routine can be interrupted by a primary or secondary 
interrupt handler. 

All software interrupt routines For a particular task are 
serialized; they don't interrupt each other, so there's no 
equivalent to the 680x0 model of nested primary interrupt 
handlers. 

Page faults are allowed from software interrupt routines. 

A software interrupt routine is analogous to a Posix signal 
or a Windows NT asynchronous procedure call. A 
software Interrupt routine running in the context of on 
application, IN IT, or edev doesn't have access to a 
driver's global data. 

SECONDARY INTERRUPT 

The secondary interrupt level is the execution context 
provided to a device driver's secondary interrupt handler. 
In this context, hardware interrupts are enabled and 
additional interrupts may occur* A secondary interrupt 


handler is a routine that runs in privileged mode with 
primary interrupts enabled but task switching disabled. 

All secondary interrupt handlers are serialized, and they 
never interrupt primary interrupt handlers; in other words, 
they resemble primary interrupt handlers but hove a 
lower priority. Thus, a secondary interrupt handler queued 
from a primary interrupt handler doesn't execute until 
the primary interrupt handler exits, while a secondary 
interrupt handler queued from a task executes 
immediately. 

Page faults are not allowed at primary or secondary 
interrupt level, A secondary Interrupt handler is analogous 
to a deferred task in Mac OS System 7 or a Windows NT 
deferred procedure call. Secondary interrupt handlers, 
like primary interrupt handlers, should be used only by 
device drivers. Never attempt to run application, IN IT, or 
edev code in this context or at primary interrupt level. 

PRIMARY INTERRUPT 

The primary interrupt level (also called hardware interrupt 
level) is the execution context in which a device's primary 
interrupt handler runs* Here, primary interrupts of the 
same or lower priority are disabled, the immediate needs 
of the device that caused the interrupt are serviced, and 
ony actions that must be synchronized with the interrupt 
are performed* The primary interrupt handler is the 
routine that responds directly to a hardware interrupt* It 
usually satisfies the source of the interrupt and queues a 
secondary interrupt handler to perform the bulk of the 
servicing, 

TASK (NON-INTERRUPT) 

The task level (also called non-interrupt level) is the 
execution environment for applications and other 
programs that don't service Interrupts, Page faults are 
allowed in this context. 
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(called cache incoherence ). Furthermore, you have to explicitly tell the PowerPC or 
680x0 processor to synchronize the cache with memory. 

Normally, the processor hardware prevents cache incoherence From causing data value 
problems. However, for some processor architectures, DMA transfers access main 
memory independently of the processor cache, PrepareMemoryForlO (for write 
operations) and CheckpointIO (for read operations) synchronize the processor cache 
with main memory. This means that DMA write operations write the valid contents 
of memory, and the processor uses the valid data just read from the external device. 

As noted earlier, some devices cannot perform DMA transfers; instead, they use 
programmed I/O , in which the CPU moves data between logical addresses and the 
device, PrepareMemoryForlO also returns the logical address that such devices 
must use. 

A SIMPLE MEMORY PREPARATION EXAMPLE 

Listing I presents a very simple example that shows how a memory area may be 
prepared for I/O. 

To simplify listings. I've often omitted data type casting. Think of all data types os 
unsigned 32 bit integers. Because of this omission, you can't implement these listings 
as written, but should base your code on the sample on this issue's CD. c 

PrepareMemoryForlO is called with one parameter, an IOPreparationTable. Among 
other things, this table specifies one or more address ranges to prepare (only one, in 
this example). Each address range is indicated by a starting logical address and a 
count of the number of bytes in the range. 

The IOPreparationTable also points to a logical mapping table and a physical mapping 
table (gLogicalMapping and gPhysicalMapping in our example). The physical 
mapping table is where PrepareMemoryForlO returns the page addresses that the 
driver can use to access the client’s buffer during DMA, The logical mapping table 
is the list of addresses that the driver must use for doing programmed I/O. 

The simplest IOPreparationTable options —- klOMinimalLogicaLMapping and 
klOLogicalRanges — are set in this example. The klOMinimalLogicalMapping flag 
indicates that only the first and last logical pages need to be mapped, while the 
klOLogicalRanges flag indicates that the data (here, the gMyBuffer vector) consists 
of logical addresses. 

Because klOMinimalLogicalMapping is set, the logical mapping table requires two 
entries for each address range; we have only one range, so our logical mapping table 
needs a total of two entries. The physical mapping table requires one entry per page; 
we set this to two entries because our 512-byte buffer may cross a page boundary. 
When writing your driver, you can use the GetMap Entry Count function in the 
DMA support library to compute the actual number of physical mapping table 
entries needed for an address range. 

If the preparation is successful, die driver performs the DMA transfer and calls 
CheckpointIO to release internal operating system structures that were used by 
PrepareMemoryForlO, PrepareMemoryForlO sets the klOStateDone flag in the 
lOPreparationTable’s state field if the entire area has been prepared. 

If PrepareMemoryForlO can’t prepare the entire area, it doesn’t set the klOStateDone 
flag, and your driver needs to call PrepareMemoryForlO again with the firstPrepared 
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Listing 1 . $ implified memory preparation 

tdefine kBufferSize 512 
fdefine kMapCount 2 

/* The buffer your driver or application is preparing */ 

UIntS gMyBuffer[kBufferSize]; 

lOPreparationTable glOTable; 

/* Logical & physical mapping tables, filled in by PrepareMemoryForlO */ 
Log!calAddres s gLogic alMapping[ 21; 

FhysicalAddress gPhysicalMapping[kMapCount]; 

void SimpleMemoryPreparation(void) 

{ 

OSStatus osStatus; 

glOTable.options = 

(klOMinimalLogicalMapping | klOLogicalRanges | klOXsInput); 
glOTable,state = 0; 

glOTable.addressSpace = kCurrentAddressSpacelD; 
glOTable,granularity = 0; 
glOTable,firstPrepared = 0; 
gXOTable.lengthPrepared = 0; 
glOTable.mappingEntryCount * kMapCount; 
glOTable.logicalMapping = gLogicalMapping; 
glOTable.physicalMapping * gFhysiealMapping; 

/* Set the logical address to be mapped and the length of the area 
to be mapped. */ 

glOTable.rangelnfo.range.base = (LogicalAddress) gMyBuffer; 
glOTable.rangelnfo.range.length = sizeof gMyBuffer; 

/* Call PrepareMemoryForlO and process the preparation. */ 
do { 

osStatus = PrepareMemoryForlO(SglOTable); 
if {osStatus 1= noErr) 
break; 

MyDriverDMARoutine 

CheckpointlO{glOTable.preparationID, kNilOptions); 
glOTable.firstPrepared += glOTable.lengthprepared; 

} while ((glOTable.state £ klQStateDone) == 0); 


field updated to reflect the number of bytes prepared in this range of memory. The 
recall ioust be done from a software interrupt routine; it cannot be performed from 
an interrupt handler. 

MORE ABOUT MAPPING 

Address ranges to be prepared by PrepareMemoryForlO may cross one or more page 
boundaries and thus may take up two or more pages in physical memory. Figure 1 
shows what the physical mapping might look like for two address ranges: the first is 
more than two pages long and crosses two page boundaries, while the second is an 
even page long and crosses one page boundary. 

Each address range maps to an area i n physi cal memory that can be thought of as 
having up to three sections: the beginning page, the middle pages, and the ending page. 
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Your program's 
logical address space 


Physical 
address space 


0 




0x1000 

Address 

ranges 

0x2000 

Starting 

Count 


address 

(in bytes) 


0x0400 

0x2800 

0x3000 

0x4400 

0x1000 




0x4000 



0x5000 



0x6000 





- 

0x5000 - 


0x6000 - 


Physical 
mapping table 

0x0400 

0x3000 

0x2000 

0x6400 

0x5000 


Figure 1. Mapping to multiple pages 

* Every address range produces a beginning page. Your data may start at an 
offset into this page, depending on the starting address of the range. This is 
true for both address ranges in Figure L The address in the mapping table 
for the beginning page points to die beginning of your data in the page. 

Notice that for the second address range in our example, the logical address 
for the start of the data, 0x4400, maps to the physical address 0x6400. 

* If your address range maps to three or more pages, some number of middle 
pages are completely filled with your data. The first address range in Figure 
1 illustrates this. 

* If your address range maps to two or more pages, the data on the ending 
page begins at the beginning of the page, hut it may cover only part of the 
page, depending on the count in your address range. 

Unfortunately, there’s no simple one-to-one correspondence between entries in the 
physical and logical mapping tables and the address range (or ranges) that a driver 
or application speci fies when it calls PrepareMemoryForlO, Because of this, the 
function that controls a driver’s DMA or programmed I/O process must iterate 
through the input address ranges and output mapping tables to compute the address 
and size of each data transfer segment. As you'll see when you look at the DMA 
support library on this issue’s CD, this turns out to be an extremely complex process. 

The DMA support library functions iterate through the address ranges and mapping 
tables, matching the two together to provide each data transfer segment in order. 
The library recognizes when two physical pages are contiguous and extends the data 
transfer length as far as possible. 

When called for the example in Figure I, the DMA support library returns five 
physical transfer segments (this example doesn’t demonstrate logical alignment 
problems). To learn how PrepareMemoryForlO’s algorithm works, I’d recommend 
that you work out the actual addresses and segment transfer lengths using pencil and 
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paper. (When you look at the DMA support library in DMATransfer.c, you’ll see a 
more mechanized approach diat I strongly recommend if you’re developing complex 
software.) 

THE DATA TRANSFER PROCESS 

Figure 2 illustrates how a data transfer might proceed through the system. It shows 
the five steps involved in a transfer that requires partial preparation of a large chunk 
of data that can’t be prepared in one gulp- The diagram also shows the proper 
execution levels for each step. As well see later, the process is considerably simpler 
without partial preparation. 


Task 

(Non-Interrupt) 


Secondary 

Interrupt 


Primary 

Interrupt 


Time 


V 7 


I. Call PrepareMemoryForlQ. 
Start DMA operation. 

Wait for interrupt. 


2, Queue secondary 
Interrupt. 

__J 


3. Call CheckpotnttO. 

Call Send Software Interrupt, 

_i 


4. Call PrepareMemoryForlQ, 

Cal SecondarylnterruptHandler2, 

I_ 


i 


5. Restart DMA operation. 


Figure 2 • The progress of a data transfer with partial preparation 

Here’s a breakdown of the steps in the data transfer: 

L The transfer starts at task (application or driver mainline) level. The driver 
must call PrepareMemoryForlO from task level because PrepareMemoryForlQ 
rnay require virtual memory page faults and has to reserve system memory 
for its own tables. After memory is prepared, the driver examines the logical 
and physical mapping tables and starts the DMA operation. Tt then waits for 
an interrupt. (Of course, the actual driver behavior depends on your 
hardware.) 

2. When the driver’s primary interrupt handler runs, it determines that another 
DMA transfer is needed, but that no more data is prepared (because the 
number of bytes transferred equals the value in the lengthPrepared field in 
the lOPreparationTable). Since another partial preparation must be 
performed, the primary interrupt handler queues a secondary interrupt and 
exits the primary interrupt. The device is in a “frozen” state: it eidier has 
data available (to read) or needs more data (to write) but cannot proceed at 
this time. I’ll talk more about this problem later. 
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3* The driver’s secondary interrupt handler starts, ft examines its internal state 
and determines that a DMA transfer has been completed, it calls CheckpointIO 
with the kMorelOTransfers flag to complete the current partial transfer 
Since another data transfer will be needed, it begins the process of calling 
PrepareMemoryForlO again, by calling SendSoftwarelntermpt to queue a 
software interrupt routine* Then, with nothing more to do, the secondary 
interrupt handler exits. The device is still frozen. 

4, The software interrupt routine runs. It updates the firstPrepared field and 
calls PrepareMemoryForlO to prepare the next segment (range of memory). 
This may require a page fault, causing the virtual memory subsystem to 
move data between main memory and die virtual memory disk file. When 
PrepareMemoryForlO finishes, the logical and physical mapping tables are 
updated and the lengdiPrepared field contains die number of bytes that can 
be transferred in the next segment. The software interrupt routine calls a 
secondary interrupt handler (which is equivalent to queuing the handler). 

5. The sequence returns to the secondary interrupt handler, and the DMA 
operation is restarted. The partial preparation algorithm continues at step 2, 
progressing through steps 2 to 5 until all data is transferred. 

The device is frozen in steps 2 to 5; it cannot proceed on the current I/O request 
until the partial preparation completes. But note that the page fault handler in step 4 
may require disk I/O; consequently, any device that can service the page fault device 
(such as the SCSI bus manager) cannot support partial preparation. Writers of disk 
drivers and other SCSI-based interface software must understand these restrictions, 

A CLOSER LOOK: SOME EXAMPLES 

Unfortunately, as a result of some necessary constraints of PrepareMemoryForlO, 
the code in Listing 1 isn’t usable in an actual device driver when the data transfer 
results in the interruption of the hardware device by the CPU. In this section, I'll 
return to the five-step transfer process outlined above, with more detail on the way 
that a driver interacts with memory preparation. I’ll illustrate the process with three 
different examples: the simple case of a single DMA transfer; the more complicated 
case where more than one DMA transfer is needed because the physical mapping 
entries are discontiguous; and finally the full five-step transfer process, complete with 
partial preparation. 

A SIMPLE TRANSFER 

Our first example uses the sample preparation shown in Figure 3, Here your 
application or driver created a simple lOPreparationTable for an application data 
buffer that's 512 bytes long and begins at logical address 0x01 B89F80, 

In this case the transfer process consists of only three steps: 

L The buffer in our example crosses a physical page boundary, so two mapping 
entries are needed. PrepareMemoryForlO fills in the logical and physical 
mapping tables and sets the lengthPrepared field. Since it has successfully 
prepared die entire buffer, it sets the kXOStateDone flag in the state field. 

After your driver uses the NextPagelsContiguous macro (in DMATfansfer.h) 
to determine that the two physical mapping entries are contiguous, it puts 
the first physical address, 0x007 7EF80, and the entire byte count into the 
DMA registers and starts die device. 

2. When the transfer finishes, the driver’s primary interrupt handler runs. It 
determines that the transfer has finished and queues a secondary interrupt to 
complete processing. 
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Prepa reMe m o ry Fa r! O 


0x01B89F80 


0x01 B8A000 


GxG077EF8Q 


0x0077F000 


Figure 3- A simple lOPreparalianTable 


3. The driver’s secondary interrupt handler calls Checkpoint! O to complete die 
transfer. It then completes the entire device driver operation by calling 
lOCora m and IsCompl ete. 

DISCONTIGUOUS PHYSICAL MAPPING 

The above example requires a single DMA transfer; however, if the physical mapping 
entries are discontiguous, die first two steps of the process become more complicated; 

1„ After preparation, your driver determines that the two physical mapping 
entries are not contiguous. Therefore, it puts the first physical address, 
Gx0077EF80, and the first byte count (I2H bytes in this case) into die DMA 
registers and starts the DMA operation. 

2. When the transfer finishes, the driver’s primary interrupt handler runs. It 
determines that the transfer has finished; however, another physical transfer 
is needed and can be performed, so it loads the DMA registers with the new 
physical address and the remaining byte count (384 bytes in this case), 
restarts the DMA operation, and exits the primary interrupt handler. 

After this DMA operation finishes, the operating system reenters the 
primary interrupt handler. Upon the completion of the entire transfer, the 
primary interrupt handler queues the secondary interrupt handler to finish 
die entire operation. 

PARTIAL PREPARATION 

The example in Figure 3 requires only a single preparation, but in some cases 
PrepareMemoryForlQ cannot prepare the entire area at once and so requires partial 
preparation. To illustrate this, I’ll change a few parameters in die lOPreparationTable. 
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• The logical address of the buffer is 0x01 B89F80. 

■ The transfer length is 20480 bytes. 

* The transfer granularity is 8192 bytes. This value limits the length of the 
longest preparation. 

Prep areMemoryForlO performs partial preparation of the data three times, as shown 
in Table l. 


Table 1. Three partial 

preparations 




Logical Mapping 

Physical Mapping 

Byte Count 

First Preparation 

0x01B9F80 

0x01 BAQQ0 

0xQO77EF8O 

OxQQ77FQOG 

4224 

Second Preparation 

0x01B8BQ0O 

0x01 B8C0O0 

0x00780000 

0x00782000 

8192 

Third Preparation 

0x01880000 

0x0188E00O 

0x00783000 

0x00784000 

8064 


'The entire transfer requires these three repetitions of the five-step transfer process: 

1. The driver prepares the first DMA operation for physical address 
OxOG77EF80, length 4224, After it interrupts, the primary interrupt handler 
queues a secondary interrupt that, when run, calls CheekpointlO and causes 
a software interrupt routine to run. This software interrupt routine updates 
the firstPrepared field from 0 to 4224 (the amount previously prepared) and 
calls PrepareMemoryForlO for the next partial preparation. When 
PrepareMeinoryForlO finishes, the software interrupt routine calls the 
secondary interrupt handler. 

2. The secondary 7 interrupt starts the next transler for physical address 
0x00780000, length 8192. When this transfer finishes, the primary interrupt 
queues the secondary interrupt, which, in turn, calls CheekpointlO and 
causes the software interrupt routine to run a second time. Phis task calls 
PrepareMemoryForlO for the next preparation and calls the secondary 
interrupt handler again. 

3. The secondary 7 interrupt handler starts the final transfer. When it finishes, 
the driver completes the entire preparation. 

LOGICAL DATA TRANSFER; PROGRAMMED I/O 

Some hardware devices do not support DMA but rather use programmed I/O, in 
which the main processor moves data between program logical addresses and die 
device. Programmed I/O is also needed when the device’s DMA hardware cannot use 
DMA in a particular situation or context — for example, a one-byte transfer. 

Some hardware devices cannot transfer data that isn’t properly aligned to some 
hardware-specific address value. For example, the DMA controller on the Power 
Aiacintosh 8100 requires addresses to be aligned to an 8-hyte boundary; it can only 
transfer to physical addresses in which the low-order three bits are set to 0. Also, data 
transfers must be a multiple of 8 bytes. To handle such cases, the DMA support 
library returns the logical addresses of unaligned segments so that a device driver can 
transfer them with programmed I/O ope rations. 
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This restriction on logical alignment means that before starting a DMA transfer, the 
driver must look at the low-order bits of the physical address and the low-order bits 
of the count. The actual data transfer process is illustrated by the code in Listing 2, 
which presumes 8-byte alignment and ignores a few additional complications. The 
ugly stuff is in the ComputeThisSegment function, which examines the global 
IOPreparadonTable and handles multiple address ranges. The DMA support library 
simplifies the procedure, as we’ll see in the next section. 


Listing 2* Data transfer with logical alignment 

LogicalAddre ss thisLogicalAddres s ; 

PhysicalAddres s thisPhysicalAddress; 

ByteCount thisByteCount, segmentByteCount; 

ComputeThisSegment{sthisLogicalAddress, sthisPhysicalAddress, 

&thisByteCount); 

if ((thisPhysicalAddress £ 0x07) != 0) { 

/* Pre-alignment logical transfer */ 
segmentByteCount = 8 - (thisPhysicalAddress & 0x07); 
if (segmentByteCount > thisByteCount} 
segmentByteCount = thisByteCount; 

DoLogicalTransfer(thisLcgicalAddress, segmentByteCount); 
thisByteCount -= segmentByteCount? 
thisLogicalAddress += segmentByteCount; 
thisPhysicalAddress += segmentByteCount; 

> 

if (thisByteCount > 0) { 

/* Aligned physical transfer */ 
segmentByteCount - thisByteCount & '0x07; 
if (segmentByteCount 1= 0) { 

DoPhysicalTransfer(thisPhysicalAddress, segmentByteCount); 
thisByteCount -= segmentByteCount; 
thisLogicalAddress +- segmentByteCount; 

} 

> 

if (thisByteCount 1=0) { 

/* Post-alignment logical transfer *7 
DoLogicalTransfer(thisLogicalAddress f thisByteCount); 


PUTTING IT ALL TOGETHER 

Here we’ll take a look at how your driver can use several of the functions in the DMA 
support library to simplify dealing with PrepareMemoryForlO. 

Before you can call any of the functions in the DMA support library to make a partial 
preparation, you need to create the system context for a software interrupt. This 
context is created by the CreateSoftwa rein ter nipt system routine, as shown in the 
InidalizePrepareMemoryGlobals function in Listing 3. Create Software Interrupt 
must be called from your driver’s intiaUzation routine because it allocates memory. 
Your driver’s interrupt handler uses a software interrupt to start a task that can 
call PrepareMemoryForlO {as described earlier in step 4 of the data transfer 
process). 
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Listing 3. IniNalizaHon for DMA 

So ftwar e I nt err aptID gN ext DMAInt erruptID; 

/* This function is called once, when your driver starts, */ 

OSErr InitializePrepareMemoryGlobals(void) 

{ 

OSErr status? 

gLogicalPageSize = GetLogicalPageSize(); 
gPageMask = gLogicalPageSize - 1? 
status = CreateSoftwareInterrupt( 

PrepareNextDMATask, /* Software interrupt routine *7 
CurrentTaskID{), /* For my device driver */ 

NULL, /* Becomes the pi parameter */ 

TRUE, /* Persistent software interrupt */ 

SgNextDMAInterruptlD]; /* Result is the task ID, */ 

return (status); 

> 


The DMA support library contains two functions that a driver can use to simplify 
processing the output from PrepareMemoryForlO: InitializeDMATransfer, which is 
called once to configure the overall transfer operation, and PrepareDMATransfer, 
which is called to set up each individual transfer. 

The MyConfigureDMATransfer function in Listing 4 calls PrepareMemorylO and 
InitializeDMATransfer to configure the transfer. This function is called by the 
mainline driver function (and by a software interrupt routine for partial preparation, 
as well see later). 

If MyConfigureDMATransfer is successful, the driver initializes the hardware to 
begin processing, I assume here that the hardware interrupts the process when it 
requires a data transfer. The primary interrupt handler is shown in Listing 5. 


Listing 4. MyConfigureDMATransfer 

/* In a production system, 

kPageCount should be retrieved from the 

operating system by calling GelLogicalPageSize. */ 

Idefine kPageCount 

4096 

#define kLongestDMA 

65536 

Idefine kLogicalAlignment 

8 

Idefine kMappingEntries ((kLongestDMA + (kPageCount — 1)) / kPageCount) 

DMATransferlnfo 

gDMATr ans f erInf o ; 

IGPreparationTable 

glOTable; 

LogicalAddress 

gLogicalMapping[2 ]? 

PhysicalAddress 

gPhysicalMapping t kMappingEntries]; 

AddressRange 

gThisTransfer; 

Boolean 

glsLogical; 


(continued on next page) 
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Listing 4. MyConfJgureDMATransfer (continued) 

OSErr MyConfigureDMATransfer( 

lOCommandCode ioCommandCode, /* Parameter to DoDriverIG */ 

ByteCount firstPrepared /* Zero at first call */ 

) 

( 

OSErr status? 

gThisTransfer.base - NULL; /* Setup for programmed I/O */ 

gThisTransfer.length - 0; /+ Interrupt handler */ 

glsLogical * FALSE; 

if (firstPrepared == 0) { 

/* This is an initial preparation for the transfer. */ 
glOTable.preparationlD - klnvalidlD; /* Error exit marker */ 
switch (ioCommandCode) { 

case kReadCominand: glOTable.options = klOIsInput; break; 
case kWriteCommand: glOTable.options = klOIsOutput; break; 
de f ault: retur n (paramErr); 

} 

ioTable.ioOptions j= 

( klOLogicalRanges /* Logical input area */ 

| klOShareMappingTables /* Share with OS kernel */ 

| klOMinimalLogica1Mapping /* Minimal table output */ 

); 

glOTable.state = 0; 

glOTable.addressSpace - CurrentTaskIDf); 
glOTable,granularity = kLongestDMA; 
glOTable.firstPrepared = 0; 
glOTable,lengthPrepared = 0; 
glOTable,mappingEntryCount = kMappingEntries; 
glOTable,logicalMapping = gLogica1Mapping; 
glOTable.physicalMapping = gPhysicalMapping; 
glOTable.rangelnfo.range.base = pb->ioBuffer; 
glOTable.rangelnfo.range.length = pb->ioReqCount; 

} 

else { /* We were called to continue a partial preparation. */ 

glOTable.firstPrepared = firstPrepared; 


status = PrepareMemoryForlO(&glOTable); 
if (status 1= noErr) 
return {status}; 

status - XnitializeDMATransfer(^glOTable, kLogicalAlignment, 
fcgDMATransferlnfo); 
return (status); 


When the primary interrupt handler determines that a data transfer is needed, it calls 
the function MySetupForDataTransfer, which tries to continue a logical (programmed 
I/O) transfer. If no logical transfer is appropriate, it calls Prep arc DMATransfer, to 
configure the next data transfer segment. This will be either a logical or a DxMA 
transfer, depending on the interaction between the user’s data transfer parameters and 
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Listing 5* The primary interrupt handler 

InterruptMemberNumber MyInterruptHandler(InterruptSetMember member, 

void *refCon, 

UInt32 thelntCount) 

{ 

OSErr status; 

if (<device has or requires more data> == FALSE) 

status = noErr; /* Presume I/O completion. */ 

else 

status » MySetupForDataTransfer(); 
if (status 1= klOBusyStatus) 

/* This partial transfer (or device operation) is complete. */ 
QueueSecondaryInterruptHandler(DriverSecondaryInterruptHandler r 
NULL, NULL, (void *) status); 
return (klsrlsComplete); 

> 

OSErr MySetupForDataTransfar(void) 

{ 

OSErr status; 

if (glsLogical && gThisTransfer. length > 0) { 

/* Continue a programmed I/O transfer* */ 

DoOneProgrammedlOByte(* ((UInt8 *) gThisTrans f er.base)); 
gThisTransfer.base += 1; 
gThisTransfer.length -= 1; 
status = klOBusyStatus; 

else { /* We need another preparation segment. */ 

status = PrepareDMATransfer(SgDMATransferInfo, kgThisTransfer, 

&glsLogical); 

if (status == noErr) { /* Do we have more data? */ 

status = klOBusyStatus; /* Don't queue secondary task. */ 

if (glsLogical) { /* Start a programmed I/O transfer. */ 

DoOneProgrammedIOByte(* ((UIntS *) gThisTransfer.base)); 
gThisTransfer.base += 1; 
gThisTransfer.length -= I; 

> 

else /* Start a DMA transfer segment. */ 
StartProgrammedlOToDevice(SgThisTransfer); 

} 

else /* This preparation is done. Can we start another? */ 
status - kPrepareMemoryStartTask; 

} 

return (status); 


the device’s logical alignment restrictions. If more data remains to be transferred, 
MySe tu pFor DataTransfer starts either a DMA transfer or another logical transfer; 
otherwise, it returns a private status value that will eventually cause a software 
interrupt routine to call PrepareMemoryForlO again to continue a partial 
preparation. 
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Listing 6 shows the secondary interrupt handler — at least the part that handles the 
DMA operation. The primary interrupt handler provides the operation status in the 
p2 parameter; the secondary interrupt handler uses this parameter to determine 
whether the operation is complete (in which case this is the final status), or whether 
some intermediate operation is required. 

Finally, Listing 7 shows the software interrupt routine that's called when the driver 
must call PrepareMemoryForlO again to perform a partial preparation. 


Listing 6* The secondary interrupt handler 


OSStatus DriverSecondarylnterruptHandler(void 


QSStatus osStatus? 


*pl, 

*p2) 


osStatus = (OSErr) p2; 
switch (osStatus) { 

case kFrepareMemoryStartTask: /* Need more preparation */ 

CancelDeviceWatchdogTimer(); 

osStatus = SendSoftwarelnterrupt.{gNextDMAInterruptID, 0); 
if (osStatus 1 = noErr) { 

/* Handle error status by stopping the device* */ 


1 

break; 

case k P repareMemoryRestart: /* Preparation completed */ 

osStatus = MySetupForDataTrans£er{); 
break; 

> 

if (osStatus 1= klOBusyStatus) { /* If I/O is complete +/ 

CancelDeviceWatchdogTimer(); 

Checkpoints(fcioTable, kNilOptions); 
IOCommandlsCompletefioCommandlD, (OSErr) osStatus); 

} 

return (noErr); 


Listing 7 . A software interrupt routine For partial preparation 

void PrepareNextDMATaskjvoid *pl, 

void *p2) 

{ 

OSErr status; 

ByteCount newFirstPrepared; 

if ((glOTable,state & klOStateDone) 1= 0) 

status = eofErr; /* Data overrun or underrun error */ 

else { /* Do the next partial preparation, */ 

newFirstPrepared - 

glOTable*firstPrepared + glOTable *lengthPrepared; 

(continued on next page} 







Listing 7. A software interrupt routine for partial preparation (continued) 

status = MyConfigureDMATransferj0, newFirstPrepared); 

/* ioCommandCode is not used, */ 

> 

QueueSecondaryInterruptHandler(DriverSecondaryInterruptHandler, 
NULL, NULL, (void *) status); 


YOUR TURN IN THE BARREL 

At times, working through the complexity of this problem felt like going off Niagara 
Falls in a barrel. There used to be a joke among the developers of the UNIX 
operating system: “We never document our code: if it was hard to write, it should be 
hard to understand.” The algorithms Pve described here were hard to write, hut I 
hope 1 was able to document anti clarify the most important features of the library 
well enough that you don't have to go through the same struggle I did. 


Thanks to our technical reviewers David 
Harrison, Tom Sauipaugh, Dove Smith, and 
George Towner, D 



Developer University 

Apple Computer, Inc. 

I Infinite Loop. M/S 305-ITU 
Cupertino, CA 95014 


It’s not just the basics anymore! 

Advanced courses from Developer University get you up 
to speed quickly on new Apple technologies. 

□ OpenDoc 

□ PowerPC 
D Newton 

□ Graphicsllmaging 

Courses are available as: 



IP i 


G 


Self-Paced Classroom 


id 


Lecture 



Online 


For detailed information, check out http://www.info.apple.com/dev on the World Wide Web, or contact the 
Apple Developer University Registrar at (408)974-4897 or fax (408)974-0544 


THE NEW DEVICE DRIVERS: MEMORY MATTERS 


99 
























Macintosh 

Q&A 


Q 

A 


How do I determine whether a Power Macintosh has PCI expansion slots? 

If there's a Name Registry, you can use it to determine whether a PCI bus exists. 
To determine whether die Name Registry exists, use the new Gestalt selector 
gestaltNameRegistryVersion (nreg 1 ). If the Name Registry exists, the value 
returned is the version number of the Registry; otherwise, gestaltUndefSelectorErr 
is returned, and you can assume that the machine doesn't have PCI slots. 


If the Name Registry exists, call RegistryEntrySearch to look for an entry 
having a property name of device_type and a property Value of pci. If an entry 
is found, there is a PCI bus on the machine. 


Q 


Our software doesn V awaken properly on a Power Book that has come out of sleep mode. 
Are there any special handling requirements to recover from sleep mode? 


A The changes to die system state when a PowerRook goes to sleep include the 
following: 

• All AppleTalk connections are lost, because the AppleTalk driver is turned off. 

* The serial ports are entirely shut down to conserve power. 


There are two Macintosh Technical Notes that relate to your situation: “Little 
PowerBook in Slumberland” (HW 24), which provides a brief overview of the 
sleep process, and “Sleep Queue Tasks” (HW 31), which presents additional 
material regarding the sleep process. The second one includes sample code that 
demonstrates a sleep queue task implementation. The sleep queue task enables 
your program to save state information that otherwise might be lost Typically, 
this is important for a networked process that needs to reestablish a connection 
upon awakening. 


Q 


Can we define our own extensions to QuickTimes Image Description structure? In other 
words y can we just attach any kind of data to the end of the Image Description structure? 
Our codec would use this data only on the Macintosh. 


A 


Yes, you can add any extended data you like, with the utility routines provided 
for this purpose (described in Inside Macintosh: QuickTime Components^ starting 
on page 4-65). You have complete control over how your codec interprets the 
extensions. Therefore, as long as the default image description handle remains 
intact {for the benefit of the various Movie Toolbox calls that depend on the 
documented structure being there), you can add whatever information you like. 
Note that Apple reserves all extension types consisting entirely of lowercase 
letters. 


Q 


We ’re trying to write a QuickTime codec, hut we're having trouble because Inside 
Macintosh: QuickTime Components was written before the universal headers , and the 
sample codec source doesn't build at all with the latest headers. Where can we get a 
QuickTime codec that builds for PowerPC under the current universal headers? 


A Until a PowerPC-native codec example becomes available, you can get the 
information you need from the Macintosh Technical Note “Component 
Manager version 3.0” (QT 5), which provides details on creating native 
components. Note that you have to use Resorcerer or Rez to create the 
component templates; ResEdit won't suffice. 
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Our codec needs to provide more options to the user than the normal image-compression 
dialog contains. The documentation suggests that it's possible to provide an extra 
Options button in the dialog, and Tve seen some applications that do provide an Options 
button for certain codecs. Is this a function of the application? How does the application 
know to do this? 

If your codec component has an exported function named CDRequestSettings, 
the standard image-compression dialog will automatically provide the specific 
button. In other words, QuickTime checks the codec component, adds the 
button (provided it’s available), tracks clicks in the button, and calls your 
CDRequestSettings routine appropriately. For furdier details, see the 
Macintosh Technical Note “QuickTime 1.6.1 Features” (QT 4) w r here 
CD Re q uestSettings is documented. 


We have a non-Macintosh device that creates and reads QuickTime movies, and we 
need to pass additional information about the images between the non-Macintosh device 
and our QuickTime codec. It seems that the logical place to put this information is in an 
ImageDescription extension (within the sample description atom), since this is about all 
that's accessible to a codec . Is the format of this extension documented anywhere? We've 
looked at the extension created by Set Image Descrip non Extension , and the format seems 
simple , hut it would be nice to know what the “official” fotvnat is. 

Chapter 4 of Inside Macintosh: QuickTime has a listing of the atoms and their 
formats. Sample description atoms are described on page 4-35. Note that each 
media format has its own sample description tables, which are not direedy 
accessible. 

The official guideline is to use, if possible, the provided APIs for creating 
sample description atoms. If you’re working on a platform for which there are 
no Toolbox APIs, you’ll have to obtain a source-code license agreement to get 
real source code showing how die atoms are constructed. (For details regarding 
licensing part or all of the QuickTime source code, contact Apple Software 
Licensing at AppleLink SW.LICENSE or (512)919-2645.) 


Our application plays QuickTime movies. Some older movies played well in System 7.1, 
but they don't play properly in System 7 J or 7.5.1. We happened to find the Apple 
Multimedia Tuner, and it solves the problem , What is the Apple Multimedia Tuner, 
who needs it, how does a customer get it , and can we distribute it? 

The real solution to your problem is just to preroll the movie before playing it, 
which is what the Apple Multimedia Tuner is doing for you. QuickTime 2*1 
incorporates all the Tuner improvements, so there’s no longer any need to 
distribute the Tuner separately 


We have a problem when we draw to an offscreen GWorld under low-memory 
conditions (when the system heap can't grow) on a Power Macintosh, The GWorld 
drawn contains digital noise. The same code works just fine in an 680x0 environment . 
Any idea what's happening? 

It sounds as if the Code Fragment Manager is unable to load the code from the 
PowerPlug library into temporary memory. This will cause QuickTime to issue a 
noCodecErr error. You should always try to catch QuickTime-generated errors, 
checking, for instance, for playback errors after each MoviesTask call like this: 




anErr = GetMoviesStatus(Movie theMovie, Track *problemTrack); 


Here’s a possible workaround to your problem: Launch a small application that 
has the QuickTimeLib (PowerPlug) library statically linked in, so that it’s 
loaded. This application should launch the main application and then kill itself. 
The second application could try to grow to a predefined size and handle low- 
memory conditions in whatever way it wants, but the CFM libraries are already 
in memory by then. 

The Code Fragment Manager will never load fragments into an application 
heap, because there’s a global registry of CFM libraries present. If another 
application registers to use a CFM library that’s in an application heap that 
subsequently goes away, this will obviously be a Bad Thing, In the 680x0 
environment, the codecs are components, and the Component Manager will 
always try to load components into the application heap if the system heap 
doesn’t have any available space. 


Q 


/ need to add print items' to a QuickDraw GX dialog box. In attempting to me the 
Experiment no. 9 sample * l found what appears to be a bug. This example uses 
GXGetMessageHandlerResFik when it calls GXSetup Dialog Pan el, bin it should call 
Cur Res File. 


A 


You’re right. Applications should call Cur Res file. GXGetMessageHandlerResFile 
is reserved lor extensions and drivers. 


For additional code examples that add print items to a QuickDraw GX dialog 
box, see the Worldwide Developers Conference 1995 Technology CD (or the 
Mac OS Software Developer’s Kit), The Fxtension Shell, Userltems, and 
Additions samples provide the basic item adding/handling code that you require. 


Q 


Where can l find some good sample code that demonstrates the techniques required for a 
“panel* with QuickDraw GX printing (as an application — not an extension)? 


There are two sample applications (“Experiment no.9” and “Banana Jr.”) that 
show how to do this. In both of these applications, the panels appear in the 
Custom Page Setup dialog. I Iowever, the sample code can easily he modified to 
add panels to the Page Setup and Print dialogs. 


Q 


How can I draw and print hairlines with QuickDraw GA? We use a picture comment 
in the normal print code , but this seems to make QuickDraw GX fail. We get a - SI 
error (reference number invalid) when we call GXGetJobError after calling 
GXFinishJoln and we sometimes get this error without the picture comment code. 


We also tried calling GXSe tShape Pen in our spool procedure. When we set it to a 
fractional value , we get a wide line, but when we set it to a wide value , such as 8, if 
works properly. What do we need to do to print fractional widths? 

Here are two ways to get QuickDraw GX to draw hairlines when printing: 

• Call GXSetShapePen(myShape, 0). This sets your pen width to 0, meaning 
as thin as possible on the output device. QuickDraw GX always draws 
hairlines at the resolution of the output device — one pixel wide. 

* Call GXSetStylePen(mySty]e, 0), This also sets your pen width to 0, with 
the same result. 
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When using GXSetShapePen and GXSetStylePen, don’t specify the pen width 
as an integer: remember that it’s a fixed-point value. GXSe tS tylePen(myStyle, 1) 
sets the pen width to 1/65536; GXSetStylePen(myStyle, ff(l)} sets it to LG. 

QuickDraw GX uses a backing store file (an invisible file within the System 
Folder) to send QuickDraw GX objects to disk when additional space is needed 
within the QuickDraw GX heap. Almost all -51 errors from within QuickDraw 
GX or an application using QuickDraw GX are caused by double-disposing of a 
QuickDraw GX object (that is, a shape, ink, style, or transform). The -51 error 
occurs because the double dispose causes QuickDraw GX to set the shape 
attributes, which indicates that it has sent the object to disk. When it needs this 
object, it goes to the backing store and tries to get it, but it’s not there. We’ve 
found a few cases where QuickDraw GX itself was double-disposing of objects, 
and these were fixed in QuickDraw GX version LL 

Before calling GXDrawShape, call GXValidateShape on the shape or shapes 
you’re trying to print. This ensures that a shape is valid before it’s drawn or 
printed. It slows things down a little, but you’ll be able to determine whether a 
shape is still available before you attempt to draw it (you might be disposing of 
a shape before you draw it). If you have an error handler installed, you usually 
receive the “shape_already_disposed” message, but you may not receive this 
message if something is wrong with the QuickDraw GX backing store. 

It’s also possible that the hairline drawing problems you’re encountering are 
related to the translation options you’re using. A translator takes your 
QuickDraw drawing commands and converts them to QuickDraw GX objects, 
based on options you provide. If you use the gxDefaultOptionsTranslation 
setting, a QuickDraw line turns into a six-sided filled polygon. When your 
object is a polygon, changing the pen width has no effect. 

To avoid translation problems, call GXIn stall QDTrans la tor with the 
gxSimpleGeometryTranslation or the gxReplaceLineWidthTransIation option. 

* gxSimpleGeomenyTranslation turns on both the simple-lines and simple¬ 
scaling translation options, and it translates QuickDraw lines into QuickDraw 
GX lines with flat endcaps. The QuickDraw GX line shape runs along the 
center of the original QuickDraw line, and it covers all the pixels of the 
QuickDraw line and more. 

• gxReplaceLineWidthTranslation turns a QuickDraw line into a QuickDraw 
GX line with a width that is the average of the original pen’s width and 
height. This option also affects the way the SetLineWidth picture comment 
is interpreted. 

Once you set the translation option, your calls to GXSetShapePen or 
GXSetStylePen should behave as you expect them to, because they’re acting 
on QuickDraw GX lines, not polygons. When you’ve installed a translator, be 
sure to remove it with GXRe move QDTran slater. To learn more about the 
translation options, see Chapter 1 of Inside Macintosh: QuickDraw GX 
Environment and Utilities. 


Q I'm trying to send messages from within a QuickDraw GX message override. I want 
to send GXWriteData to flush the buffet'so that I can send the GXGetDeviceStatus 
message . / override the GXHandlePanelEvent message. In my override, sending 
messages causes the system to crash. What would cause this to happen? 
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The crash is occurring because there’s no connection to the printer at the time 
you're sending the message. You have to send die GXOpenConnection, 
GXWriteData, and GXCloseCoimection messages. Note that when you send 
GXOpenConnection, QuickDraw GX puts up the default job status dialog for 
a short time. If you don’t want this dialog to appear, you can override the 
GXfobStatus message to prevent it from being shown. See also Dave Kersey’s 
Print Hints column, “Writing QuickDraw GX Drivers With Custom I/O and 
Buffering,” in develop Issue 21. 


Q 


/ used the sample driver showing haw to do custom dialogs as the basis far the 
compatibility part of our QuickDraw GX PostScript driver, and I added an Options 
dialog to it for our printer-specific features, I have two problems with it when using 
applications that arm Y QuickDraw GX-mvare. First , the paper-type always defaults 
to the fifth paper-type listed in the resource file, so whichever paper-type is the fifth one 
listed becomes the default paper-type in the QuickDraw GX compatibility driver This 
is, of course, reflected in the Page Setup dialog. Second, the driver always defaults to 
having the v Print to File ” checkbox on. What can 1 do about these problems? 


Both die quirks you describe (improper default paper-type and the “Print to 
File” checkbox defaulting to on) can be fixed by modifying the PREC 0 
resource in the driver. 


When an application using old-style printing calls PrintDefault to request the 
default print record from the current printer driver, the driver gives it the 
contents of the ’PREC' 0 resource. Then, when the application calls PrJobDialog 
or PrSdDialog, it passes in that print record. In its overrides, the QuickDraw 
GX printer driver interprets die contents of the old-style print record to set up 
the states of the dialog's buttons, checkboxes, and so on. 

To determine which paper-type radio button to select in the Page Setup dialog, 
QuickDraw GX compares the page rectangle specified in the old-style print 
record to the rectangles of all the paper-types in the driver (or paper-type 
extensions, such as “3-Hole Punch"), and tries to find the best match. Because 
of the way that die old-style print record in the sample is defined, that best 
match turns out to be the fifth paper-type in your list. So, to fix this quirk, all 
you have to do is change die bounds setting in the ’PRFt2 0 resource so that it 
matches the bounds of the US Letter paper-type in die driver. 

To determine die state of the “Print to File” checkbox, the driver looks at the 
UlOffset field of the old-style print record. (You might not think to look here, 
but old-style print records are limited to 120 bytes, and there was no better 
place to store this information.) Because the ’PREC 0 resource in this driver 
has this field set to 1, the checkbox defaults to on. So, to fix this, all you have to 
do is set the field to 0. 


Q 


/ want to create an extension for the Page Setup/Format dialog that performs 
flipping 37 functions. Is it feasible to create an extension for the Page Setup/Format 
dialog rather than the Print dialog? 


There’s nodiing to prevent you from creating an extension that adds a panel to 
the Page Setup dialog. Most printing extensions add to the Print dialog because 
in most cases this is the proper place to add a panel that affects the entire 
output, and because what extensions usually do is best suited for the Print 
dialog. Drivers and applications, on the other hand, typically add to die Format 
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dialog. Note that if you’re trying to modify an existing sample extension so that 
it adds to the Page Setup dialog, you have a bit of work to do. 

There's a way that you can test your flipping code without writing a new 
extension, by the way Applications can override the GXJobDefaultFormatDialog 
or GXFomiatDialog message. There are two examples (“Experiment no.9 !, and 
“Banana Jr/ T ) that demonstrate overriding GXFormatDialog. You might try 
adding your flipping code to one of these. 

A car passed me the at he?' day with one of those round white cmmtry stickers that said 
WAL Where was it from? 

Sierra Leone. 


In QuickDraw 3D, when we have the interactive Tenderer on and we tty to turn off 
the draw context's cIcarlmageMethod (setting it to kQ3ClearMethodNom ), it still 
clears. This works properly with the wireframe rendered hut we need this feature in the 
interactive Tenderer, since we're pasting in background pictures that we want to act as a 
backdrop to our 3D models. The interactive Tenderer always obliterates the background 
with the clearlmageCotor. What can we do? 

Unfortunately this is a renderer-dependent feature that's supported by the 
wireframe Tenderer, but not the interactive Tenderer. We intend to provide a 
“Clear with picture” method in the next major release of QuickDraw' 3D 
(version 1.1). 


The in teractive Tenderer doesn 't draw flat surfaces that are parallel to the camera view 
direction with the orthographic camera , but the wireframe Tenderer does . We put in a 
“floor 77 of polygons, and when we look along the edge of the floor with the orthographic 
camera, it totally disappears . With the wireframe Tenderer, we see a line where the floor 
is, which is as expected. Wlmt gives? 

Filled primitives have no thickness, so when you look at them edge-on, they do 
not appear. Lines, however, are a mathematical abstraction, so they always 
appear to be one pixel thick (when you zoom in on a line, its thickness doesn’t 
increase). While this may seem somewhat odd, it’s the w ay many libraries work. 
To achieve the effect you want, make the floor a thin box, and texture-shade die 
top surface. If die depth of the box is nonzero, it appears to be a slab-like 
structure, and it won’t disappear when viewed edge-on. 


If we iterate through the vertices in a mesh , will the vertices still he in the same order as 
they were when they were added? 

Yes. The ordering of the vertices doesn’t change until you duplicate the mesh or 
write it out. A duplicated mesh (or one diat was written out and read back in) 
doesn’t necessarily have the vertices in the same order as when diey were added. 


When I tty to render models with different types of lights, the point light and the 
directional light work comedy, but the spot light doesn't. Any idea why? 

The spot light's cone of light needs to touch a number of vertices for any effect 
to be seen. If the light is attenuated, it may have insufficient intensity when it 
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strikes the surface. The cone of light also needs to be wide enough to cover a 
significant area of the object being modeled for the Tenderer to draw a 
reasonable effect. 
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What effect does the TQ3 View Object parameter have in the bounding box calculating 
routines (Q3 ViewJStartBoundingBox and Q3View_EndBoundingBox)? The old 
geometric-object routine descriptions refer to world space, but if this is so, there's no need 
for a view parameter ,: However, if the view i camera is used , the bounding box is returned 
in camera coordinates rather than view coordinates. Since both are useful , would it be 
possible to have both sets of routines available? I can apply a ro tation/translation 
matrix to all of the items to be drawn to generate camera coordinates from a world 
coordinate routine, but I need to find out if I need to do this or if this has already been 
accomplished. 


A The QuickDraw 3D routines return the bounding box or bounding sphere in 
local coordinates. Part of the reason that the API was modified to use submit 
calls, rather than having separate picking, rendering, and writing calls, is that 
the transformations that are applied matter more than the camera. Since 
these modifications were made, the submit calls for everything (including 
transformations, if they’re not stored in the group) can be in one submission 
function that’s called from inside the picking, rendering, or writing loop. If you 
need the bounding box for a single geometry in its own coordinate space, this 
is also easy to do — you can write a simple routine that performs bounds 
calculations on a single object. For example: 


Q3View J3tartBoundingBox; 
Q3xxx_Submit ; 
Q3View_EndBoundingBox j 


Q Does QuickDraw 3D prefer meshes or NURB patches? Which kind of data yields bettei ■ 
performance? 

A Meshes are convenient for editing, but they take quite a bit of memory, so the 
tradeoff is time versus space. NURB patches are more convenient for dealing 
with surfaces as a whole and for representing surfaces at different tessellations. 

Although meshes exhibit better performance than NURB patches m the first 
version of QuickDraw 3D, later versions may have improved patch performance. 
In the meantime, consider experimenting with the tessellation factor for your 
patches, since overtessellating reduces performance. 


Q Vd like to make sure that Vm Turning under version 1.0.2 of QuickDraw 3D. When I 
get the version from QSGetVersion the major version is 1 and the minor version is 0 , 
but I can V get the revision (the third number). Is there a Gestalt selector for this? 

A Starting with version 1 .0.2, there is a Gestalt selector to get the version of 
QuickDraw 3D: gestaltQD 3D Version. The return value has two bytes for the 
major version, a byte for the minor version, and a byte for the revision. So for 
version 1.0.2 Gestalt will return 0x00010002. Note that this Gestalt selector 
works only with QuickDraw 3D 1.0.2 and later. 


Cl The Color Sync documentation (in the reference section of Inside Macintosh: Advanced 
Color Imaging) states that each color component in the L *a*b* color space is within the 
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range ofO to 65,28(1 Shouldn't this be 0 to 65,535, since this is the value for the other 
spaces and the value in the ICC Profile Format Specif cation? 

A No. The correct maximum value for this particular color space is 65,280 

(OxFFOO)* Note that the final documentation is now available as Advanced Color 
Imaging on the Mar OS, published by Addison’Wesley* 

Q What exactly are the internal parameters for the ColorSync quality settings? That is, 
how large a lookup table is built for “draft" versus “mmuiF versus “best 71 ? 

'Hie quality fiag bits provide a place in the profile for an application to indicate 
the desired quality of a color match (potentially at the expense of speed and 
memory). In ColorSync 2.0, these bits do not mandate the use of one algorithm 
over another, or one lookup table size over another; they Ye just recommendations 
that a particular CMM may choose to ignore. 

Let's look at liow the default Apple CMM uses the quality recommendations 
specified in the flag bits. Other CMMs, of course, will have different 
implementations. 

When Apple's CMM builds a color world from two or more profiles, and one 
or more of these profiles contain TRC curves or A2Bx tables, the CMM also 
builds a private, multidimensional lookup table* The quality Hag bits determine 
the resolution of this private table. Draft quality is treated the same as Normal 
quality, so there are really only two effective settings, Normal/Draft and Best. 

In most cases, the quality is only slightly better in Best mode, so the difference 
is difficult to see, unless one of the profiles has a high gamma value. For high 
gamma values, die extra resolution in the lookup table is helpful. 

Best mode typically takes twice as long to build a color world (about two 
seconds, versus one second in Normal/Draft mode). However, once the color 
world is built, the time to use it is the same for either mode (approximately 1.5 
MB/second on a Power Macintosh 8100/110). 

Best mode also requires significantly more memory than Normal/Draft mode* 

A color world typically requires 120K of heap space in Best mode versus 25K in 
Normal inode, and the “high-water” memory requirement while a color world 
is being built is typically 300K for Best mode versus 90K for Normal mode. 

Note again that these guidelines apply only to the default Apple CMM. 1 he 
tradeoffs between speed, quality, and resources may be quite different for other 
CMMs. 

Q / want to go directly firm an input CMYK space to an output CMYK space (without 
going through an intermediate three-component space) to preserve the original 
GCR/UCR settings . Can / create a ‘Tink* profile for this purpose? If I do, will I have 
to write my own CMM to use it? 

A You can build a CMYK-to-CMYK device-link profile for this purpose, and you 
can use it without w riting your own CMM. 

v.v '.; Pm using the ColorSync call CWCheckBitMap to do gamut checking in a plug-in for 
Photoshop. The result bitmap is not what / expected, and seems to be different every 
time I try it. Any idea what could be going on? 
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CWCheckBitMap sets each pixel in the result bitmap to black if the 
corresponding pixel in the source bitmap is out of the gamut. It doesn’t, 
however, set each pixel in the result bitmap to white if the pixel in the source 
bitmap is in the gamut. If you aren’t erasing the bitmap before calling 
CWCheckBitMap, that would explain what you’re seeing. Always erase the 
result bitmap to white before calling CWCheckBitMap, (This is also true of 
CWCheckPixMap and CWCheckColors.) 


If I have a physical drive ID , how can I determine whether that drive is a network 
volume? Pm not sure where to look , and I need to know whether the in form at km is 
dependable and not subject to change. 

Under the current Macintosh file system, there’s no completely dependable way 
to determine whether a volume originates over a network or is implemented on 
a local disk. This is the result of the way external file systems are implemented 
— a third party can build a network file system in a variety of ways. 

You can, however, easily determine whether a volume uses the AFP (AppleShare) 
file system, which in many cases is adequate. To make this determination, 
compare the driver refNrnn in the drive queue entry to the AppleShare client’s 
refNum. 


The following code enumerates the drive queue and displays the relevant 
information: 


main{J 
{ 

QHdrPtr 

DrvQElPtr 

short 

OSErr 


drvQHdr ^ GetDrvQHdr()? 
dqeP; 

afpRefNum = 0; 
errNo; 


// Get the driver refNum for AFP, 

errNo = OpenDriver{"\p.AFPTranslator" f fiafpRefNum); 
if (errNo 1- noErr) 
return 


// Scan each drive in the drive table, 
dqeP = (DrvQElPtr) drvQHdr~>qRead; 
do { 

// Is it an AFP volume or SCSI device? 
if (dqeP~>dQRefNum == afpRefNum) printf("AFP")? 

} while (dqeP ={DrvQElPtr) dqeP->qLink); 

} 

For other third-party file systems, such as DECNET and NFS, you have to 
determine the name of the driver and then compare it to the AppleShare client’s 
refNum. 


/ need to get a list of files in a particular directory. Should I use PBCatSearch, or 
should I use indexed PBGetCathifo or PBGetFlnfo requests? 


The ri Cat” in PBCatSearch stands for “Catalog” and that’s what PBCatSearch 
searches: the whole volume catalog. You can specify that matches found by 






PBCatSearch be limited to a specific directory by setting the fsSBFIParlD bit in 
the ioSearchBits field of the parameter block, and then specify the directory to 
match on by setting ioFIParlD in ioSearchlnfol and ioSearchInfo2 to the 
directory ID you’re interested in. However, PBCatSearch may not be what you 
want to use, for a couple of reasons: 

• The matches PBCatSearch finds by matching based on ioFIParlD are only 
in that one directory, not in any of that directory’s subdirectories, 

• Because the whole catalog file is searched, this is usually not the fastest way 
to look through a specific directory’s contents. 

If you need matches in both the directory and its subdirectories and you don’t 
want to search the whole volume, there’s a routine in the MoreFiles sample code 
named IndexedSearch that’s compatible with PBCatSearch’s parameter blocks, 
except that IndexedSearch lets you specify what directory you want to search. It 
uses indexed PBGetCatlnfo calls to search a directory and its subdirectories. 

If you need matches from only a single directory (and not from that directory’s 
subdirectories), you can use the MoreFiles routine named GetDirltems. This 
routine uses PBGetCatlnfo to index through a directory’s entries and returns 
FSSpees to the entries found. In this case, making indexed PBGetCatlnfo calk 
is much faster than searching the whole catalog with PBCatSearch. 


Q 


/ need to nest two Custom GetFile dialogs , hut Pm running into trouble. Under some 
circumstances after the user dismisses the second dialog (usually via the Cancel button), 
l lose all of the custom controls in the first dialog . Whafs happening? 


The Standard File Package is not reentrant, so there really isn’t a way to nest 
standard file dialogs that will work right. The real problem is in the resources 
that the Standard File Package uses for the dialog items. When the second, 
nested dialog closes, it releases resources that the first dialog is still using; that’s 
why your items are getting messed up. 


There’s a kludgy workaround, but it will break under future systems. You could, 
however, use sequential calls to the Standard File Package instead of nesting 
them. This is a bit of a pain, hut should accomplish what you want, Here’s how: 
Put up the first dialog. In your filter routine, when the user clicks the control 
that is to bring up the nested dialog, set a flag in your application signifying 
“bring up other,” and tell the Standard File Package that you’re done with the 
first dialog by passing item 1 or 2 back. After you put up the second dialog and 
process it, bring the original dialog back. This will be a little messy cosmetically 
as the dialogs open and close, hut it’s the only way to do it in a manner that will 
remain compatible. 


Q 

A 


Whafs the best way to remove an attached leech? 

The best way we know of is to rub a freshly cut lemon or lime on it. Most 
leeches will detach immediately, and die a writhing, horrible death shortly 
afterward. Fire and salt are also said to be effective. 


These answers are supplied by the technical Have mare questions? See the Macintosh 
gurus in Apple's Developer Support Center* Technical G&As on this issue's CD. [Older Q&As 

can be found in the Macintosh G&A Technical 
Notes on the CD.)* 
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DAVE JOHNSON 


THE VETERAN 
NEOPHYTE 

The Right Tool 
for the Job 


Dynamic programming languages are cool. Once 
you’ve tasted dynamic programming, it’s hard to go 
back to the old, crusty, static way of doing things. But 
the tact remains that almost all commercial software is 
still written with static languages. Why? 

Recently I took a class in Newton programming. For 
me personally the Newton isn’t a very useful device, 
only because I never carry around a notepad or calendar 
nr address book or to-do list and I don’t have a need to 
collect any sort of data out in the field. Rut even 
though it’s not terribly useful to me, it is very useful to 
a lot of people — and useful or not, it’s a really cool 
device. Programming the Newton, for those of you 
who haven’t had the pleasure, is very, very' different 
from programming the Macintosh in C or C++ or 
Pascal, and is incredibly attractive in a lot of ways. 

The language that you use to program the Newton, 
NewtonScript, is an example of an object-oriented 
dynamic language, or OODL. (See? Even the acronym 
is cool.) This means a number of things, but the upshot 
is that it’s very programmer-friendly and very flexible. 
Now, I don’t pretend to be an expert in languages, not 
by a long shot, so I can’t offer any incisive comparisons 
with other “modern” languages, hut 1 am cell you what 
ir feels like for a dyed-in-the-wool C programmer to 
leap into this new and different world. It feels great. 

One well-known feature of dynamic languages is 
garbage collection, the automatic management of 
memory. Objects in memory that are no longer needed 
are automatically freed, and in fact there is no way to 


explicidy free them other than making sure that there 
are no references to them any more, so that the 
garbage collector can do its thing. I didn’t fully realize 
how much time and effort and code it takes to deal 
with memory management until I didn’t have to do it 
anymore. There’s something almost naughty about it, 
going around cavalierly creating objects in memory 
without worrying about what to do vrith them later. 
After a lifetime of living in mortal fear of memory leaks, 
it feels deliciously irresponsible. 1 like it. I like it a lot. 

Newton Script’s object model is refreshingly simple and 
consistent. There are die usual “simple” data types — 
integers, real numbers, Booleans, strings, and so on — 
and only two kinds of compound objects: arrays and 
frames. An array, as you might expect, is simply a linear, 
ordered group of objects, and the individual objects are 
referenced by their index (their position in the array). 
Frames are an unordered collection of items in named 
slots; you refer to a particular item by rhe name of its 
slot. Frames are also the only NewtonScript objects 
that can be sent messages, and the message is simply 
the name of a slot that contains a function. 

Because NewtonScript is dynamic, variables or frame 
slots or array members can hold any kind of data, 
including other arrays nr frames, or even functions, and 
the kind of data can be changed at any time. The size 
of the array or frame can be changed anytime, too; you 
can add or delete items as needed, without worrying 
about managing the changing memory requirements. 
This kind of flexibility is a big chunk of what makes 
dynamic languages so, well, dynamic. Such a thing is of 
course unimaginable i n a static language, where each 
byte must be explicitly allocated before it’s needed, 
carefully tracked while used, and explicitly deallocated 
when you’re done with it 

NewtonScript is also introspective, meaning that all 
objects “know” all about themselves. (Isn’t that a nice 
term? I like the idea of a language being introspective — 
sitting there, chin in hand, pondering itself.) The type 
of a piece of data is stored with the data, and named 
items keep their names. In fact, everything in memory 
is coherent, with a well-defined identity; there is no 
possibility of undifferentiated bits getting schlepped 
around, no possibility of a dangling pointer or a string 
being interpreted as a real number. In static languages, 


DAVE JOHNSON recently enrolled his smallest dog — named lo 
(eye-oh) but affection ately called The Stink let — in an agility class. 
Dag agility is a sort of obstacle course for dogs, with ramps and 
jumps and tunnels and poles to climb and leap over and crawl and 
weave through, Dave got so involved that he started building 
agility courses in the living roam. He came to his senses, thankfully 
before creating any permanent installations. * 


Dave is easing up on his working life: beginning with the next 
issue, hell be working 3/4 time, He had to give up some things, 
and it was decided (reasonably enough) that helping to edit the 
rest of develop was more important than writing this column. Look 
for guest Neophytes in coming issues, with perhaps the occasional 
installment from Dave,* 
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of course, all that design-level information is thrown 
out at compile time, and doesn't exist in the running 
program at alL There's nothing but undifferentiated 
bits, really. What a mess. 

And that means that debugging, for the most part, has 
to take place at die machine level. By the time the 
program is running, ids just a maze of pointers and 
bytes and instructions, fine for a machine but nasty for 
humans. Of course, to combat this we have elaborate, 
complex programs called source-level debuggers. They 
give you the sense that the names still exist, thank 
goodness, but it's just a trick, and depends on an 
external file that correlates symbols with locations in 
memory. If you don't have the symbol file, you're out of 
luck. (Confession time: In my regular C programming 
I avoid low-level debugging like the plague. Usually I’d 
rather spend an hour in a source-level debugger than 
spend five minutes in MacsBug— I know, I know, I'm 
a wimp —- precisely because all the information that 
helps me to think about my program, the names and 
so on, still "exist” in the source-level debugger. In 
NewtonSeript, there isn't even such a thing as low-level 
debugging! All that design information is right there in 
the guts of die running program. Hallelujah!) 

With dynamic languages like NewtonSeript, you can 
let go of the details of the machine's operation, and deal 
with your program's operation instead — you can think 
at the design level, not the machine level. And ids an 
incredible relief to float free of the bits and bytes and 
pointers and handles and memory leaks and messy 
bookkeeping. Most of the ponderous baggage that comes 
along with writing a computer program goes away I 
mean really, how much longer must we approach the 
machine on its terms when we want to build something 
on it? Users were released from that kind of bondage to 
the machine's way of doing things long ago. So what 
are we waiting for? Obviously we can't program the 
Macintosh in NewtonScript (more's the pity) but why 
aren't we all chucking our C++ compilers in exchange 
for Prograph or Lisp or Smalltalk or Dylan? Well, 
some of us are. But I think there are two major hurdles 
to overcome before dynamic languages become 
mainstream: the need for speed, and inertia. 

Dynamic languages carry their own baggage, of course. 
In the same way that making the Macintosh easier for 
people to use made it harder to program because the 
complexity and bookkeeping were shunted behind die 
scenes, making programming languages easier to use 
also requires new behind-the-scenes infrastructure 


and complexity. (Somebody has to do the memory 
management, after all.) 'Phis usually results in a bigger 
memory footprint and slower execution. For “normal" 
operations, we're long past the point where that 
mattered: the hardware is beefy enough to handle it 
without blinking. But software always pushes the limits 
of the hardware. Consequently there are still times 
when it's important to squeeze every drop of 
performance out of the machine. And dynamic languages 
are just not very good at that. (I don't think you’d 
want to write your QuickDraw 3D Tenderer in Lisp.) 

So any dynamic language that hopes for mainstream 
commercial acceptance had better have a facility for 
running hunks of “external” code. That way you could 
write the bulk of your program in a dynamic language, 
but still be able to write any time-critical parts in your 
favorite static language and plug them in. You'd lose 
the protection of the dynamic language when running 
the external code, but that's a reasonable tradeoff. 

Inertia is the other big problem. People, once they know 
one way to do something, are often loath to change it, 
especially if they’ve been doing it that way for a long 
time. I'm guilty of this in my own small way: every time 
I learn a spiffy, liberating new way to program I think 
I’ll never go back to the “old” way. But the next time I 
set off to write some code I automatically reach for the 
familiar tools, not the new ones. (Lucky for me, the 
only way to program the Newton is in NewtonScript.) 

Fortunately, neither one of these hurdles will stop the 
evolution of our tools. It's unstoppable, if perhaps slower 
than we might like. There's already a whole spectrum 
of cools available. From Assembler to AppleScript, 
Pascal to Prograph, there are tools that allow anyone 
with enough interest to teach their computers to do 
new things. The line between users and programmers 
continues to blur, and dynamic languages can only help 
that process. I love the thought of putting programming 
tools into the hands of “nonprogram mers” — kids, 
artists, hobbyists — and seeing what they come up 
with. You can bet it will be something new, something 
that people tied to the machine would never have 
thought of. I can't wait. 


RECOMMENDED READING 

* Unleashed: Poems by Writers' Dogs, edited by 
Amy Hempel and Jim Shepard (Crown, 1995). 
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Q 


The on-line discussion groups fir Newton developers have a lot of references to 
compatibility these days. My application works fine on the 120 , 110 , //wd 10(9 models. 
Does that mean Tm compatible? 


A 


Good question. Compatibility doesn't mean your application works now, but 
that it J s written in such a way that it will work on future Newton devices and 
operating systems. There are several APIs and methods for doing things on the 
120, 110, and 100 models that will work with them but are not necessarily 
compatible with future releases of the operating system. 


There are two main points to observe for the sake of compatibility: 

• If it's not documented, don't use it, 

* Catch exceptions; they can occur (especially if you ignore the first point). 


Since compatibility is such an important question, it: will be the focus of this 
column. The rest of the column will cover the most common breaches of 
compatibility. Where applicable, there will be an example of the incompatible 
and compatible ways of doing things. After reading this and making copious 
notes (especially where you find yourself saying “Oh dear” and “Oh no!”), you'll 
be in a position to make your code compatible. We also recommend that you try 
out your application with the Compatibility App Package (which is on this 
issue's CD and is available from various on-line services). 


Note that we refer often to the Newton Toolkit platform file functions. The 
Toolkit documentation and platform file release notes describe these functions, 
which are provided in lieu of future APIs. You should use these platform file 
functions where applicable. Call the code directly and don't modify it. That is, 
use the call/with syntax; don't place the code in a slot in your application and 
use message sending. 


UNDOCUMENTED GLOBAL FUNCTIONS 

There are four common offenders here: CreateAppSoup, SetupCardSoups, 
MakeSymboI, and GetAll holders. 

The function kRegisterCardSoupFunc in the platform file replaces CreateAppSoup 
and Setup Card Soups. It's much simpler to use than the undocumented functions: 

// RIGHT way 

constant kSoupName : = "MySoup:MYSIG" ; 
constant kSoupIndices ’[]; 
constant kAppGbject t- ’["Item", "Items"]; 
call kRegisterCardSoupFunc with 

[kSoupName, kSoupIndices, kAppSymbol, kAppObject); 

// *** WRONG way *** 

CreateAppSoup(kSoupName f kSoupIndices f EnsureInternalf[appSymbol]) # 
Ensurelnternal(kAppObject)J; 

AddArraySlot{cardSoups , kSoupName); 

AddArrayS1Ot(cardSoups, kSoupIndices); 

SetupCardSoups(); 


The llama is the unofficial mascot of the questions to NewfonMail or eWorld DR LLAMA or 

Developer Technical Support group in Apple's to AppleLink DR.LLAMA. The first time we use a 

Newton Systems Group. Send your Newton-related question from you, well send you □ T-shirt. 1 
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The fix forMakeSymbol is to call the Intern function: it does the same thing as 
MakeSymbol and it's documented. 

There’s no replacement function for GetAllFolders; just don’t call it. 

UNDOCUMENTED GLOBAL VARIABLES 

The three most common misused global variables are cardSoups, extras, and 
userCon figuration. 

There are two uses of cardSoups: one is to register a card soup; the other to 
unregister it. Registering is taken care of with kRegisterCardSoupFunc (see above). 
Unregistering is done with another platform file function, kUnRegisterCardSoupFunc: 

// RIGHT way 

call kUnRegisterCardSoupFunc with (kSoupName); 

// *** WRONG way *** 

S etRemove(c a rdS on p s, kS oupN ame); 

SetRemove(cardSoups, kSoupIndices); 

You should never access the extras global variable. Not only is this variable 
undocumented, but so is its format. Both are subject to major revisions. The 
platform file function kSetExtrasInfoFunc is provided for setting information about 
items in the extras drawer. The most common use of this function is to give your 
application a different icon (see the ExtraChange DTS sample code on the CD), 

There are also platform file functions to manipulate userCon figuration: 

* kGetUserConfigFunc gets a slot from the userCon figuration soup 
entry. 

* kSetUserConfigFunc lets you set user con figuration information, 

* kEiushUserConfigFunc should be called when you’ve changed user 
configuration information. 

// RIGHT way 

local userName js call kGetUserConfigFunc with ('name); 

if userName then 

begin 

if StrEqual(userName, "Doctor") then 

call kSetUserConfigFunc with ("name, "The Doctor"); 
call kFlushUserConfigFunc with (); 
end; 

U *** WRONG way *** 
if userConfiguration.name AND 

Str£qual(userConfiguration.name, "Doctor") then 
userConfiguration.name "The Doctor"; 

UNDOCUMENTED SLOTS AND METHODS 

This is a broad category of problems. The most common is keyboard Chicken in 
the root view. But there are others, like cursor.current, paperRoll.dataSoup, 
dockerChooser in the root view, UnionSoup:Add, and anything in a built-in 
application. Unfortunately, there is no right way to access most of these. The 
exceptions are cursorxurrent and Add. 
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// RIGHT way 

local currentEntry cursor:Entry(J; 

myUnionSoup;AddToDefaultStore(anEntry); 

H *** WRONG way *** 

local currentEntry cursor.current; 

myUnionSouprAdd(anEntry); 

Also, don’t rely on the routing slips, such as maiISlip and printSlip, being in the 
root view. You can, however, still use those symbols in your routing frame. 

UNDOCUMENTED MAGIC POINTERS 

If you use one of these, you know it. Just think what w ould happen if the magic 
pointer changed from a view to a string: you would get some pretty bad behavior. 
Note that most of this could be dealt with by catching exceptions. 

STORE AND SOUP ASSUMPTIONS 

All you can assume is that store 0 is the internal store. You can’t rely on there being 
only one other store, nor can you rely on the position of a store in the array returned 
by GetStores. Also, don’t assume that another store is a card or even that there is just 
one store per card. 

If you support moving or copying items between stores, you shouldn’t find the title 
of the store. Use the constant ROM_eardAction as provided in the platform file: 

// RIGHT way 
routingFrame := { 
print: ..* 

card: ROM_e a rdAction 

1 

In addition, don’t assume that your soup will exist on every store. Currently, if you 
register your union soup, it’s automatically created on every store that enters the 
Newton; however, this may change in the future: 

// right way 

GetUnionSoup(kSoupName):AddToDefault$tore(anEntry); 

// *** WRONG way *** 

astore:GetSoup(kSoupName):Add(anEntry); 

Remember that Addlb Default Store or Add could throw exceptions. Wrap your calls 
to these functions in exception handlers. 

Finally, if you support the soup change mechanism, don’t assume that the change is 
adding or deleting an entry. It could he something else, such as a soup being created 
or removed from a store. 

SCREEN SIZE 

Don’t assume the screen is any particular size. It could be larger or smaller than 
current devices. It could also be wider than it is tall. Your application size setup 
routine (usually in the viewSetupFormScripr) should take this into account. Have 
maximum and minimum sizes. Close your application if it can’t handle the current 
screen size. 
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// Code to close your application 
constant kUnsupportedScreenSize : = 

11 WiggyWorld does not support this screen size"; 

DefConst)"closeMeFunc, func(x) x:Close()); 

:Notify(kNotifyQAlert, Ensure!nternal(kAppName), 

EnsureInternal(kUnsupportedScreenSize )); 

AddDeferredAction(closeMeFunc r [self]); 

UNDOCUMENTED FEATURES OF DATA TYPES 

Rely only on the features and details of built-in data types that are documented. 
There are three common problem areas: order of slots in a frame, precision of 
integers, and implementation of strings. 

The order of slots in a frame is undefined* It just so happens that in the current 
implementation the first 20 slots are returned in the order added. This is not a 
documented feature, so don't rely on it. 

Integers are documented as having at least 30 bits of precision* This doesn't mean 
they'll always be 30 bits; they could be wider (as anyone who has used compiled 
NewtonScript can tell you)* Note that compiled NewtonScript integers may not he 
32 bits; they also follow the “at least 30 bits” rule. 

The biggest offender is assumptions about how strings are implemented. Don't rely 
on strings being null terminated or being composed of two-byte Unicode characters* 
The practical upshot is that you should use StrLen to find the length, and StrMunger 
(or &) for length changes. Don't use Length, SetLength, or RinaiyMunger with 
strings. Don’t use the array accessor to set a string; you can check a character, but 
don't set a character. 

MISCELLANEOUS BITS 

Don't send messages directly to the IGBox; use the kSendFunc platform file function. 
Nor should you read the items in the IGBox soups. 

Also note that there are platform file functions to register and unregister for Find 
that you should use. 

Always use SetValue when you're changing the view or other system values. 

Use only the body slot in items that you route. Don't assume that slots other than 
body will survive the routing process. On a related note, don't rely on the category 
slot of fields in your SetupRoutingSlip method either. 

Don't rely on the closing order of views in the viewQuitScript. If you need to 
do some ordered cleanup, you can initiate your own message (for example, 
myViewQuitSeript) from the view that first receives the viewQuitScript, 

Replace system functions and messages at your peril. It's possible they wall support 
other data types in the future (for example, to take NIL now where before they only 
took a string). 

Don't assume anything about the built-in applications. Don't assume that they exist, 
or that their soups are there, or that the view structure will stay the same. If you do 
need to use a system feature (for example, a particular prototype, global function, or 
root method), test your assumptions. 
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local cardFileExists := GetRootO-cardfile; 

if cardFileExists then 
begin 

local cardFileSoup GetUnionSoup(ROM_cardfilesoupname); 

if cardFiieSonp then 


end; 

// :-0 

if GetRootf).keyboardChicken then 
begin 

end; 

Current Newtons have two levels of Undo; this may change. There could be more or 
fewer levels and it could change to Undo/Redo. Its safest to call AddUndoAction 
from inside your undo action; this will support Undo/Redo if we implement it, but 
will do nothing if we do not. 


Thanks fo our Newton Partners for the questions Have more questions? Take □ look at 

used in this column, end to jXopher Bell, Henry Newton Developer Info on AppleLink.* 

Cote, Bob Ebert, David Fedor, Stephen Harris, 

Jim Schram, Maurice Sharp, James Speir, and 
Bruce Thompson for the answers * 


Want to Sho«J off your cool code? 



YOUR NAME HERE 


Do you have code that solves a problem other Macintosh 
developers might he having? Why not show it off by writing 
about it in develop? We’re always looking for people who might he 
intereseed in s u b ini tting an article or a col umn. If you 1 d 1 ike to 
spotlight and distribute your code to thousands of developers of 
Apple products, here’s your opportunity. 

If you’re a lot better at writing code than writing articles, don’t 
worry. An editor will work with you. The result will be something 
you’ll be proud to show your colleagues (and your Mom). 

So don’t just sit on diose great ideas; feel the thrill of seeing them 
published i n develop ! 

For Author’s Guidelines, editorial schedule, and information 
on our incentive program, send a message to DEVELOP on 
AppleLink, develop@applelink.appIe.com on the Internet, or 
Caroline Rose, Apple Computer, Inc,, 1 Infinite Loop, 

Cupertino, CA 95014. 
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KON & BAL'S PUZZLE PAGE 


Zoning Out 



KONSTANTIN OTHMER 
AND BRUCE LEAK 


See if you can solve this programming puzzle, presented in the form of 
a dialog between Konstantin Othmer (KON) and Bruce Leak (BAL). 
The dialog gives clues to help you. Keep guessing until you're done; your 
score is the number to the left of the clue that, gave you the correct answer. 
Even if you never run into the particular problems being solved here , 
you'll leaf some valuable debugging techniques that will help you solve 
your own programming conundrums. And you'll also learn interesting 
Macintosh trivia. 


BAL IVe got a small problem Pd like you to help me with, 

KON Who’s paying the airfare this time? 

BAL Nothing like that, IPs really quite straightforward, and surprisingly 
reproducible. The problem is that sometimes when Pm using 
Microsoft Word 5. La and I pull down a menu, when I let go of the 
menu there’s garbage on the screen where the menu was. 

KON That was a problem they were having in the beta release, but I think 
ids fixed in the final version of Windows 95. 


BAL Actually, this is on a Power Macintosh 6100, and I haven’t yet installed 
Windows 95 on top of my SoftPC, which runs on my 68000, wdiieh is 
being emulated by Gary’s emulator. 

KON Microsoft is still in the loop. 

BAL Well, it’s not just a Microsoft problem. T can’t seem to make it happen 
with Word by itself It only seems to happen if I run and quit cc:Mail 
before running Word, 

KON That dam Justice Department! Without them you could just be 

running Microsoft mail, and you probably wouldn’t have this problem. 

'Fry running Word; then launch and quit cc:Mail. Does it still 
happen? 


100 BAL Now r Word is working fine. In fact, Word works in every case — at 
least as far as this problem is concerned -— unless I launch and quit 
cc:Mail before launching and quitting Word, And the interesting thing 
is that it only happens wdth the Modern Memory Manager on. 


KONSTANTIN OTHMER AND BRUCE LEAK 
KON has been holding a steady job at Catapult 
Entertainment for many months now, but he 
spends more time playing soccer than working. 


BAL is at the front of the self-employment line and 
has finally moved out of his hotel and into a 
house. Rumor has it that behind the house there's 
a big archery Field.* 
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KON Just run your machine with the classic Memory Manager, I have 
problems running THINK C’s debugger when I use the Thread 
Manager and the Modern Memory Manager, There’s just too many of 
these kinds of bugs to deal with! 

BAL Not so fast, QuickDraw. The Modern Memory Manager gives you lots 
of great new features. First of all, your machine will rim faster. In 
addition to being ported native, it also uses much more efficient 
algorithms. It keeps track of free blocks in a separate list, keeps track of 
heap zones to make RecoverHandle work better, and has a back 
pointer so that blocks can be walked either way, drastically decreasing 
heap-walking time and making things much more efficient — 
especially when virtual memory is on. Also, the Modem Memory 
Manager was designed to be bus error proof, in that it returns from 
any internally generated exception by returning an error to its caller 
(though this was changed in the latest version of the Modern Memory 
Manager, as you may have read in the Balance of Power column in 
develop Issue 23). Finally, in the old Memory Manager moving the 
partition between the system and Process Manager heaps was a total 
nightmare; this problem was solved in the Modern Memory Manager. 

KON Anytime you port something native you have two choices: rewrite the 
code directly, preserving internal algorithms and data structures, or 
rethink and reimplement, preserving only the top-level application 
interface. The first choice virtually guarantees compatibility but makes 
it difficult to maintain in the future, while the second gives you slightly 
less compatibility hut a much better upgrade path, better maintainability, 
and a much more efficient system. It sounds like they went with the 
second choice, hut at the obvious expense of some short-term 
compatibility problems. And it seems like that’s what we’re dealing 
w i th here. 


BAL I hanks for the philosophy lesson. Are you going to solve the problem? 

KON OK. Launch and quit cc:Mail and check all the heaps. Look for 

orphaned memory, locked blocks being left around, or any other signs 
of an application not properly cleaning up after itself. 

BAL I need to install MacsBug to do that. Til install version 6.5dl T because 
it has some new PowerPC features in case we need them. 


KON I bn a fra i d we w ill. 

90 BAL So after we quit cc:Mail, the system heap grew some, but all the heaps 
seem fine. We have an extra 128-bvte pointer, and we have five extra 
handles for a total of almost 32K, hut three of those (25K) are purgeahle. 

KON All this extra stuff lying around certainly explains why I have to reboot 
every couple of hours. 


BAL Yeah, and those OS engineers really worked on that problem. On 
System 7.5 you get a pretty picture and a nice thermometer bar! 

KON So try the patch demd. It will tell you what traps have been patched. 
Before you run cc:Mail, type 


patch s 


to grab a snapshot of all rhe traps. When you’re in cc:Mail, just type 
patch 
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and you’ll get a list of all the traps that have been patched. It’s a great 
way to find random skankiness. 

BAL The only OS trap that they patch is _Rename, and they patch the 

Toolbox traps _Pack8, _UserDday, _SysEn\ _LoadSeg, _UnloadSeg, 
and _ExitTnShell. 


KON OK, and what’s still patched after the application quits? 
BAL Nothing. It seems to totally clean up. 

KON Wonderful. What does Word patch? 


80 BAL The OS traps _Rename and _CompactMem, and the Toolbox traps 
_Pack8, _UserDelay, _HiIite Window, _FrontWindow, _SysError, 
_LoadSeg, and _ExitTbShell. 

KON There seems to be a lot of overlap. We should check a do-nothing 

generic application. I bet the system is magically patching some stuff 
when it runs an application. 

70 BAL It turns out that all those traps except _HiliteWindow, JFrontWindow, 
_CompactMem, and _UnloadSeg are always getting patched. 


KON It figures. Word is augmenting parts of the Memory Manager and 
getting in on some Window Manager action, and cc:Mail is playing 
games with the Segment Loader. Where’s that book on Macintosh 
programming guidelines? 


65 BAL I don’t think they read that in Redmond. By the way, even though 
menu code is fairly boilerplate, this one’s a mixed bag. Netscape, 
SiinpleText, and FindFile work fine, but Word and THINK Reference 
fail consistently. 

KON Boy, times have changed, I remember when you used to just dive right 
into MacsBug, disassemble a bunch of code, and get to the bottom of 
these problems. Now you’re looking at what SimpleText does 
compared to Word! 


BAL I’m not the one who’s doing it, I don’t even touch the computer 
anymore. It’s one of my henchmen, Paul Young. 

KON Anyway, there are two ways the hits behind the menus get redrawn. If 
plenty of memory is available, they get back-buffered and restored with 
Copy Bits. If there’s not much memory, an update event is generated, 

BxAL Since Word is the only application running at the time, we have plenty 
of memory. 

KON Ser a breakpoint on Copy Bits and pull a menu down. The first break 
will be when die bits are being saved. Let’s look at the address, step 
over the call, and make sure the right data was put there. When you let 
the menu up, you’ll break on CopyBits again. Is the source data correct 
— that is, is the source our previous destination? 

BAL The base address when the bits are restored isn’t the same as the base 
address when they get saved. 


60 


KON Where is the base address? Is it part of a handle that moved? 

BAL The base address for the restore is $40810000. 

KON Someone is dereferencing zero! It sounds like the bits are getting saved 
in a handle, and somehow the handle is getting trashed. Let’s follow 
the handle from the save and see what happens to it. 
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When the bits are being saved, the base address is part of a handle in 
MultiFinder temporary memory* The handle is $438 bytes long* 

What happens to that memory on the restore? 

The memory still exists, and the data is fine. It's just that the PixMap 
doesn't point there anymore. 

So we need to figure out where the Menu Manager is storing the 
PixMap anti why that location is getting trashed. 

The Menu Manager uses SaveBits and RestoreBits, which allocate 
memory for the pixels using the offscreen buffer calls that return 
PixMaps. The PixMap base address does double duty: when it's 
unlocked it's a handle; when it's locked it's a pointer. There's a flag in 
row Bytes to indicate what state it's in* To go from the locked state to 
the unlocked state, the G World routines call Recover Handle* 

Let's break on RecoverHandle and see what we get back. 

It returns 0* But why? 

it's kind of weird that this happens only with the Modern Memory 
Manager* In the old Memory Manager, you had to set the heap zone 
before calling RecoverHandle. The Modern Memory Manager 
relaxed this restriction and keeps a tree of valid heaps* When you call 
Recoverliandle, it walks die heap tree* If cc:Mail is somehow 
corrupting the tree, RecoverHandle will fail. 

Nice theory. I low are you going to test that? 

E.T.O. 17 has a debugging version of the native Memory Manager 
that will print out diagnostics anytime weird stuff happens. Let's install 
it and reboot* 

When you boot, you drop into MacsBug with the message "Bad 
pointer being passed to Recover! landle 0003 0020,” It looks like “PC 
Exch a n ge ” w as lo a ding. 

Let's try booting with the extensions off Use the Extensions Manager 
so that you can keep MacsBug, the Memory control panel (so that 
we're sure we're in the Modem Memory Manager), and the 
Debugging Memory Manager* 

Wien I run the Extensions Manager, I break into MacsBug with the 
message “Bad handle; are you unlocking a fake handle?” 

A complete treatise on all the memory crimes committed in the 
Macintosh is beyond die scope of this column. 

Without superfluous extensions, the problem at boot time goes away, 
but we still have the problem in Word* 

Well, let's look at the zones and see if everything looks OK* Let's do an 
hz to list all the heap zones. 

OK. But hz doesn't use the heap tree, so if you want to check the heap 
tree you'll have to do it manually. 

Great. I'll use the SmartFriends debugging trick and call Jeff to figure 
out how to do that. 

The heap tree is part of the zone header. The system zone starts at 
$2800, and a pointer to the next zone starts at offset $20. $2820 
contains $1672DF0. 
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That should be the Process Manager zone. But that number is really 
big. How could that be? How many fonts do you have installed?! 

Since the system heap can grow, we put the Process Manager zone 
header at the end of the block, so we don’t have to move the header 
every time the heap size changes. 

The next zone in the Process Manager is nil, since at die top level there 
are only two zones: the system zone and the Process Manager zone. 

Let’s look at die child zones inside the Process Manager. 

The child zones are pointed to by offset $24 in the zone header. 

The first child zone is the Word zone, which corresponds to what we 
got from hz. And the Word zone header has no child zones. 

So the world makes sense so fan Does the next zone pointer make 
sense? 

It’s kind of wacky. It points inside die Word heap! 

That’s a problem. Does that zone header look reasonable, at least? 
No. it’s trash. It looks like Word code. 


KON What happens if you don’t run cc:Mail before running Word? And 
how does the Memory Manager know how to update die zone 
headers? There’s no call to explicidy destroy zones, only create 
them. 


BAL I’ll take the second question first. Zones are created by InitZone, and 
they’re never explicidy destroyed. In the IVlodern Memory Manager, 
there’s new logic in DisposcHandle that checks to see if the handle is 
a zone; if so, it assumes the zone is destroyed and updates the heap 
tree. 


KON Will the skankiness ever end? 

15 BAL If I run Word without first running cc:Mail, the heap tree is OK. 

KON Now we just need to figure out why the heap tree is getting trashed. 
Even diough the tree update algorithm is implicit, it seems pretty 
good at first blush. Let’s go through the failing scenario and compare 
die heap zones to the tree and figure out when they diverge. 


10 BAL 


When we run cc:Mail, hz doesn’t agree with the zone structure we get 
by walking the heap tree. Here’s what the two structures look like: 


System zone 


Zone 


Handle to cc:Maif process 


Process Manager zone 


System zone 





Zone 


Stock 

Zone 


Process Manager zone 
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KON So the cc:Mail zone is smaller than the handle of the memory it’s in. 
Someone limited the size of the application zone* In the heap tree 
view, it's clear why: another zone is being allocated; 32K is left between 
he zones, and that space is being used for the stack. 

BAL The reason hz can’t find the second zone is that before the Modem 
Memory Manager, no one kept explicit track of the zones. Ba sically, 
the hz command has to search for the zones. It does this by starting 
from die system zone, which is always pointed to by low memory (and 
is usually located after the trap tables at $2800). From the system heap 
zone header, it can find the zone trailer Right after that block is the 
Process Manager zone header. It walks all the blocks in a zone and 
finds all the handles that look like other zones. It starts by assuming 
that the handle contains a zone, and then checks to see if the zone 
header points to a block that looks like a trailer and if the trailer points 
back to the zone header. When it looks for zones inside other zones, it 
assumes that they begin either at the start of the handle or right after 
anodier zone. Since cc:Mail has its stack space between the two zones, 
the hz command can’t find it. 

KON OK. Unfortunately we’re not debugging the hz command. But that 
probably gives us a clue as to why the Modern Memory Manager is 
getting confused. Ic seems to keep pretty good track of the zones that 
are getting created, since that’s easy by just watching InitZone. But it 
gets confused when the zones are being disposed of, since it does that 
by watching DisposeHandle. 

BAL Exactl y. The heap tree gets trashed when cc: Ma i 1 quits, since the 

Modern Memory Manager assumes that there’s only one zone (and 
perhaps its children) in any handle. So when it sees the dispose, it 
throws away the first zone and all its children, but it doesn’t throw 
away the second zone. It works fine with the old Memory Manager 
since no one ever explicitly keeps track of all die zones. But the 
Modern Memory Manager uses the heap tree for RecoverHandle, and 
the tree is trashed, so either the machine crashes or you get garbage. 

KON That’s pretty interesting. In this case, neither cc:Mail nor Word did 
anything wrong. The way cc:Mail used the Memory Manager was 
nonstandard, and when the algorithms in the Modem Memory Manager 
changed, there were some interesting cases that fell through die cracks. I 
think the newer version of cc:Mail no longer allocates zones this way. 

And die Memory Manager will undoubtedly soon be smarter. 

BAL Nasty. 

KON Yeah. 


SCORING 

70-100 In the end zone 
50-65 Middle ground, the Twilight Zone 
25-45 Out there in the ozone 

5-20 Low memory, zoned out* 

Thanks to Jeff Crawford and Bill Knott for reviewing this column. Special thanks to Rocket Scientist 
Paul Young, who originally found this puzzler and had the tenacity to narrow it down to a reproducible 
case.* 
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callStdBits flag (StdPk) 77 
Cancel button, in alerts 66 
Can Re turnD ata O fType, s cri pta b 1 e 
objects and 19 

cardSoups, Newton Q & A 113 


caution alerts 60-61 
CDRequestSettings, Macintosh 
Q & A 101 

CheckpointlG, PCI device drivers 
and 85-87, 91 # 92, 93 
clearImageMethod (QuickDraw 
3D), Macintosh Q & A 105 
Cl one Desi gna tor, 

TAbstractScriptahl eObject and 
17 

CMMs (ColorSync), Macintosh 
Q&A 107 
CmpSoundHeader 46 
CMYK-to-CMYK devicedink 
profile (Macintosh Q & A) 107 
codecs (Macintosh Q & A) 100, 
101 

Code Fragment Manager, 
Macintosh Q & A 101-102 
coerced records, Apple events and 

11-12 

collection object, token collections 
and 21 

col lector objects, deep searches 
and 25 
ColorSync 

L*a*b* color space 
(Macintosh Q & A) 
106-107 

quality settings (Macintosh 
Q & A) 107 

CompareProperty, compa rative 
search specifications and 22-23 
comparison descriptors 22 
resolving 16 

whose clause resolution and 

12, 14-15 

compressed audio (Sound 
Manager) 46-48, 49, 53-55 
Compresslmage (QuickTime) 80, 

81 

ComputeThisSegment, 

lOPreparationTable and 94 
containers (OpenDoc) 30, 31 
container suite (OpenDoc) 31 
content property (OpenDoc) 38 
CopyBits, KQN & BAL puzzle 
119 

CreateAppSoup, Newton Q & A 

112 

Create Element event, dispatch 
method for 21 
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create-mark-token callback, OSL 
and 9 

CreateNewElement, sending 
Apple events to 20, 21 
CreateSoftwarelntemipti 
PrepareMemoiyForlG and 

94-95 

CurResFile (QuickDraw GX), 
Macintosh Q & A 102 
cursor.current, Newton Q & A 

113-114 

CWCheckBitMap (ColorSync) 
107-108 

D 

data compression, printing images 
with 72-83 

data-loading function, printing 
large compressed images 

77-78, 79 

data transfer process (PCI device 
drivers) 90-94 

with logical alignment 93-94 
with partial preparation 
90-91,92-93, 98-99 
See also DMA transfers 
D eel areCl assD ata, scriptable 
objects and 19 

DeclareMinClassData, scriptable 
objects and 19 

Decompress!mage (QuickTime) 

76 

deep searches, whose clause 
resolution and 24-25 
default button, in alerts 66 
DefauItType, scriptable objects 
and 19 

descriptor lists (OSL) 8-9 
device drivers (PCI), preparing 
memory for 84-99 
dictionaries, for implementing 
scripting 28-29 

direct memory access. See DMA; 
DMA transfers 

D i re ctO b j ectl ter a tor, scri p ta bl e 
objects and 17-18 
direct parameter, of Apple events 7 
dirty flag (OpenDoc) 3 8 
DisposeDesignator, 

TAbstractScripta bleObject and 
17 

dkherCopy transfer mode 
(QuickDraw) 76 
DMA (direct memory access) 84 
DMA support library 84, 87, 89, 
90, 94-99 


DMA transfers 85-99 

with discontiguous physical 
mapping 92 
initialization tor 95 
with partial preparation 
90-91, 92-93, 98-99 
simple 91-92 

dockerChooser, Newton Q & A 

1 13 

DoDriverlQ, PCI device drivers 
and 85 

DoScript (ToolServer) 71 
double buffer bypass (QuickDraw 
3D) 42, 43 

draft permissions (OpenDoc) 37 
drafts (OpenDoc) 31, 37 
DR Emulator control panel, 
PowerPC and 57 
dynamic behavior objects, 

scriptable objects and 25, 26 
dynamic programming languages 
110-111 

E 

El e men tlte ra to r, scri p ta bl e obj eets 
and 7 18 

encode field (Sound Manager) 46 
errAEEventNotHandled, and 
whose clause resolution 10, 

12, 13 

Evans, Dave 56 

event-first dispatching, scriptable 
objects and 20 

“Execution Levels for Code on the 
PCI-Based Macintosh” 

(Saul pa ugh) 86 

ExportAIFF (Sound Manager) 54 
Externalize (OpenDoc) 35, 37-39 
externalizing parts (of OpenDoc 
documents) 35-36, 37-39 
extras, Newton Q & A 113 
ExtSoumlHeader 46 

F 

("Compress!mage (QuickTime) 

80,81 

FDecompressImage (QuickTime) 

76 

Femicola, Pablo 42 
FindMatchingSound (Sound 
Manager) 50 
FindNextCoinponent 

(Component Manager), Sound 
Manager and 46-48 
focus (of OpenDoc storage units) 
32-33 


formAbsolutePosition, scriptable 
objects and 18,23 
fonnName, scriptable objects and 

18 

form Whose key form 10 
handling in the object 
accessor 1 1 
foundation classes, for 

implementing scripting 17-23 
4PM performance tool, PowerPC 
and 57-58 

frames (NewtonScript) 1 1 0 
frequencyCmd command (Sound 
Manager) 51-52 

G 

garbage collection, in dynamic 
programming languages 1 10 
Gelphman, David 72 
gestaltQD3 DVersion, Macintosh 
Q & A 106 

GetAJIFolders, Newton Q & A 

112-113 

GetCom ponentl n fb (S ound 
Manager) 48 

GetCompressionInfo (Sound 
Manager) 46 

Get Data event handler, methods 
used by 1 8 

GetDirltems (MoreFiles sample 
code), Macintosh Q & A 1 09 
GetHardwareSettings (Sound 
Manager) 50 

GetLogiealPageSize, virtual 
memory and 85 

GetMapEn try Count, PCI device 
drivers and 87 
C TCtMaxCom pres s i o n S i ze 
(QuickTime) 80, 81 
GetProperty, scriptable objects 
and 18-20,22 

getRateMultiplierCmd command 
(Sound Manager) 52 
GetSoundHeaderOffset (Sound 
Manager) 46 

GetStores, Newton Q & A 114 
“Getting Started With OpenDoc 
Storage” (Lo) 30-41 
getVolumeCmd (Sound Manager) 

51 

“Graphical Truffles” (Thompson 
and Femicola), making the 
most of QuickDraw 3D 42-44 
“Guidelines for Effective Alerts” 
(Parsons) 59-68 
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GWorld (offscreen), drawing to 
(Macintosh Q & A) 101-102 
GXDrawShape, Macintosh Q & A 

103 

GXFc jrmatDialog, ove rr i d i n g 
(Macintosh Q & A) ] 03 
GXGetMe ssa geHan d3 erRes Ft I e 
(QuickDraw GX), Macintosh 
Q&A 102 

GX I nstallQDTrans I a to r, 
Macintosh Q&A 103 
GXJobDefaukFonnatDialog, 
overriding (Macintosh Q & A) 

105 

GXJobStatus, Macintosh Q & A 

104 

GXOpenConnection, Macintosh 
Q&A 104 

G X Rem ove Q DTra ns 1 ato r, 
Macintosh Q&A 103 
gxR ep I aeeLineWt d th Tra nslation, 
Macintosh Q&A 103 
GXSetShapePen, Macintosh 
Q&A 102-103 

GXSetStylePen, Macintosh Q&A 

102-103 

gxSimpleGeometry r lransktion, 
Macintosh Q&A 103 
GXValidateShape, Macintosh 
Q&A 103 

H 

hairlines, in QuickDraw GX 
(Macintosh Q&A) 102-103 
human interface guidelines, alerts 
59-68 

hz command, KON & BAL 
puzzle 120, 121-122 

I 

Image Compression Manager 
(QuickTime), compressing/ 
decompressing image data 73 
ImageDescription (QuickTime) 

75-76 

extending (Macintosh 
Q&A) 100, 101 
ImplementClassData, scriptable 
objects and ] 9 
Ini pi enien tMinClassData, 
scriptable objects and 19 
Indexed Search (More Files sample 
code), Macintosh Q&A 109 
In i tia li zeDMATr a n sfer, 

PrepareMemoryForlO and 95 


Ini d a 1 izePre pare M em oryGlobals, 
PrepareMemoryForlO and 

94-95 

InitPart (OpenDoc) 35, 36, 37 
InitPartFromStorage (OpenDoc) 
35-36, 39-41 

InitZone, KON & BAL puzzle 

121,122 

interactive Tenderer (QuickDraw 
3D) 42 

Macintosh Q&A 105 
Interface Definition Language 
(IDL), Open Doc and 31, 36 
Intern, Newton Q&A 113 
IOBox, Newton Q&A 115 
I (3Com m a n dls C om p I e te, 

PrepareMemoryForlO and 92 
IO P rep a rati c mTabl e 

GomputeThisSegment and 
94 

PrepareMemoryForlO and 

87, 90, 92 

i 

Johnson, Dave 110 
JPEG image compression 
codecs supporting 80 
performance measurements 
80-82 

pri n ti ng i m ages wi th 72-8 3 
JPEG Print with Dataload sample 
application 78 

JPEG Print sample application 

75, 82 

K 

kAEIDoMarking flag, GSL and 9 
kAEIDoWhose flag, OSL and 10 
keyAEIndex parameter 

(typeWhoseDescriptor) 12 
keyAETest parameter 

(typeWhoseDescriptor) 1 2 
keyboardChicken, Newton 
Q&A 113 

kFlnshUserConfigF unc, Newton 
Q&A 113 

kGetUserConfigFunc, Newton 
Q&A 113 

klOLogi cal Ranges flag, 

PrepareMemoryForlO and 87 
klOMinimalLogical Mapping flag, 
PrepareMemoryForlO and 87 
klOStateDone flag, 

PrepareMemoryForlO and 87, 

91 


kMorelOTransfers flag, 

PrepareMemoryForlO and 91 
kODPropPreferredKind property 
(Open Doc) 39 
"KON & BAL-s Puzzle Page” 
(Othmer and Leak), Zoning 
Out 117-122 

kRegisterCardSoupFunc, Newton 
Q&A 112, 113 
kSetExtrasInfoFunc, Newton 
Q&A 113 

kSetUserConfigFunc, Newton 
Q&A 113 

kUn RegisterCardSoupFunc, 
Newton Q&A 113 
kWaitFc) rAsyn c S ea rchesl b- 
Complete message, deep 
searches and 25 

L 

L*a*b* color space (ColorSync), 
Macintosh Q&A 106-107 
LaserWriter 8-2.2, printing JPEG 
compressed images 81-83 
LaserWriter 8.3, printing JPEG 
compressed images 73-74, 
81-83 

Leak, Bruce 1 17 
Length, Newton Q&A 115 
Lo, Vincent 30 

logical addresses, virtual memory 
and 85 

logical data transfer, 

PrepareMemoryForlO and 87, 
89, 93-94, 96, 97 
logical descriptors 22 
resolving 15 

whose clause resolution and 

12, 14-15 

logical mapping tables, 

PrepareMemoryForlO and 87, 

88-90 

logical terms descriptor, whose 
clause resolution and 12 

M 

Macintosh Q&A] 00-109 
mailSlip, Newton Q&A 114 
MakeSymbol, Newton Q&A 

112-113 

mapping tables, for address ranges 

88-90 

mark-adjusting callback, OSL and 

9 

marking, OSL and 7, 8-10 
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mark token 

OSL and B, 9 
See also tokens 

mark-token callback, OSL and 9 

Maroney, Tim 69 

memory 

preparing for I/O 87-88 
See also 

Pre pareMemoryFior IO 
Memory Management Unit 
(MMU), remapping logical 
addresses 85 
meshes (QuickDraw 3D) 

Macintosh Q & A 106 
order of vertices in 

(Macintosh Q & A) 105 
Microseconds (Toolbox) 42 
Mi now, Martin 84 
MMCRO register, PowerPC and 
58 

Modern Memory Manager, KON 
& BAL puzzle 117-118, 120, 

122 

movable modal dialogs, as alerts 

60, 62 

MPW commands, running with 
Tool Server 69-71 
“MPW Tips and Tricks” 

(Maroney), TbolServer Caveats 
and Carping 69-71 
MyCon figu reD M A'lransfer, 
PrepareMemoryForlO and 

95- 96 

MyDataLoadingProc 
(QuickTime) 78, 79 
MySetupFor Data Transfer, 
PrepareMemoryForlO and 

96- 97 

N 

Name Registry (Macintosh 

Q & A) 100 

“New Device Drivers, The: 
Memory Matters” (Minow) 

84-99 

NewEra sample application 42-43 
NewHandle (QuickTime) 80 
Newton compatibility 112-116 
Newton Q & A: Ask the Llama 

112-116 

Newton Script 110-111 
Newton Toolkit platform file 
functions 11 2 
NextPagelsContiguous, 

PrepareMemoryForlO and 91 


Normal/Draft mode (ColorSync), 
Macintosh Q & A 107 
note alerts 60 

NURB patches (QuickDraw 3D), 
Macintosh Q & A 106 

o 

object accessor callbacks, OSL and 
8 

object accessor functions, for 
implementing scriptahi lity 29 
object-first dispatching, scripta hie 
objects and 20 

object-marking callback, OSL and 

9, 10 

object model hierarchy, for 
implementing scripting 28 
object specifiers (of Apple events), 
resolving 8 

Object Support Library (OSL) 7-8 
marking 7, 8-10 
whose clause resolution 7, 

10-15 

octet (SOM) 34 

OD Byte Array (OpenDoc) 33-34 
ODContainer (OpenDoc) 31 
ODDocument (OpenDoc) 31 
ODDraft (OpenDoc) 31 
ODPart (OpenDoc) 36 
ODPersistentObjeet (OpenDoc) 
36 

OD Property Name (OpenDoc) 32 
ODStorageUnit (OpenDoc) 31, 

32-33 

manipulating value data 33 
ODValueType (OpenDoc) 32 
Olson, Kip 45 
OpenDoc 

data interchange 30, 31 
structured storage model 

30-41 

OpenDoc part editors, alert icon 
for 62 

Othmer, Konstantin 117 

p 

PackBits compression, printing 
images with 81-82 
page boundaries 

address ranges and 88 
virtual memory and 85 
page faults 

and PCI-based Macintosh 
computers 86 
virtual memory and 85 


pages 

mapping address ranges to 

88-90 

mapping to multiple 89 
virtual memory and 85 
Page Setup dialog, adding a panel 
to (Macintosh Q & A) 

104-105 

papcrRolLdataSoup, Newton 

Q&A 113 

ParentObject, scriptable objects 
and 18 

Parsons, Paige K, 59 
part editors (OpenDoc) 30,31 
reconstructing parts 38, 

39-41 

pan kind (OpenDoc) 38, 39 
pans (of OpenDoc documents) 

30, 35-41 

cloning 34, 36 
externalizing 35-36, 37-39 
initializing 36-38 
life cycle of 35 
parent in itia I i zati on 3 6 
reconstructing 38, 39-41 
wrapping of 37 
part wrappers (OpenDoc) 37 
PBCatSearch, Macintosh Q&A 
108-109 

pBestType property, of scriptable 
objects 18, 19 

PBGetCatlnfo, Macintosh Q&A 

109 

PCI-based Macintosh computers 
device drivers 84-99 
execution levels for code 86 
PCI bus (Macintosh Q&A) 100 
PCI device drivers 

data transfer process 90-94 
DMA transfers 85-99 
preparing memory for 84-99 
PCI expansion slots (Macintosh 
Q&A) 100 

pClass property, of scriptable 
objects 1 8, 19 

pComents property, of scriptable 
objects 18 

pDefaultType property, of 
scriptable objects 18, 19 
permissions (OpenDoc) 31,37 
persistent objects (OpenDoc) 31, 

36 

persistent storage (OpenDoc) 30, 

35 

physical addresses, virtual memory 
and 85 
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physical mapping tables, 

PrepareMemoryForlO and 87, 
88-90 

PMCI register, PowerPC and 58 
PMC2 register, PowerPC and 58 
pName property, of scrip table 
objects 18, 19 
position code (OpenDoc) 33 
PostScript Level 2 printers, 
support for JPEG image 
compression 02-83 
POWER Emulator control panel, 
PowerPC and 57 
PowerPC 

advanced performance 
profiling 56-58 
cache misses 56-57, 58 
TREC' 0 resource (QuickDraw 7 
GX), Macintosh Q & A 104 
P r epa re D MATr ansfer, 

PrepareMemoryForlO and 95, 
96 

PrepareMemoryForlO 

DMA transfers 85-99 
PCI device drivers and 

84-99 

and programmed I/O 87, 

89, 93-94, 96, 97 
u se r d a ta t ran s fers 85-87 
primary interrupt handlers, PCI- 
based Macintosh and 86, 93, 97 
primary interrupt level, on PCI- 
based Macintosh 86, 90 
printing 

compressing uncompressed 
data 78-80 
with JPEG image 
compression 72-83 
large compressed images 
77-78, 79 

“Printing Images Faster With 
Data Compression” 

(Gelphman) 72-83 
PrintPICTtoJPEG sample 
application 78-80, 82 
printSIip, Newton Q & A 114 
Process Manager zone, KON & 

BAL puzzle 121-122 
programmed I/O, 

PrepareMemoryForlO and 87, 
89, 93-94, 96 r 97 
Project Drag 3 

properties (of OpenDoc storage 
units) 32, 33 
Pro p ertyAp p 1 i esToP r oxy, 
scriptable objects and 22 


property description tables, 
scriptable objects and 19-20 
proxy tokens, token collections 
and 21-22 
Purge (OpenDoc) 36 
purging (OpenDoc) 36 

Q 

Q3Renderer_Sync (QuickDraw 
3D) 42 

QTMA (QuickTime Music 
Architecture) 3 
QuickDraw 3D 42-44 

custom attributes 43-44 
debugging 44 
getting version of 

(Macintosh Q & A) 106 
improving accelerator 
performance 42 
interacting with input 
devices 42-43 
interactive Tenderer 

(Macintosh Q & A) 105 
setting file type 43 
QiuckDraw GX 

adding panels to dialogs 
(Macintosh Q & A) 102 
adding print items to dialogs 
(Macintosh Q & A) 102 
and hairlines (Macintosh 
Q&A) 102-103 
and message override 
(Macintosh Q & A) 
103-104 

PostScript driver (Macintosh 
Q&A) 104 

QuickDraw pictures, image data 
compression 73, 75 
QuickDraw printer drivers, and 
image data compression 74 
QuickTime 

codecs (Macintosh Q&A) 

100 , 101 

compressing audio 53-55 
converting movies to AIFF 
files 54-55 
data-loadi ng function 

77-78, 79 

image data compression 

75-78 

Sound Manager and 52-55 

R 

rateCmd command (Sound 
Manager) 52 


rateMidtiplierCmd (Sound 
Manager 3.1) 52 
reconstructing parts (of OpenDoc 
documents) 38, 39-41 
RecoverHandle, KON & BAL 
puzzle H8, 120, 122 
Release (OpenDoc) 36 
ResolveComparison Operator, 
whose clause resolution and 
14-15, 16 

Resolve Logical Descriptor, whose 
clause resolution and 14 
Resolve WhoseDescriptor, whose 
clause resolution and 13 
Resolve Whoselest, whose clause 
resolution and 13-14 
ROM_cardAction, Newton Q&A 
114 

s 

Saulpaugh, Tom 86 
scriptability, implementing 27-29 
scriptable applications 27-29 
AppleScript and 26 
foundation classes for 1 7-23 
whole clause resolution 6-26 
Scriptable Database sample 
application 

dispatching methods 20 
for whose clause resolution 

15-17 

scriptable objects 

access methods 18-20 
class data cables 19 
dynamic behavior 26 
elements of 17-18 
properties of 18-20 
property 7 description tables 
19-20 

search specifications 22-25 
sending events to 20-21 
token collections 21 -22 
Scriptable Text Editor 28,29 
scripting (OpenDoc) 31 
SearchDeep, whose clause 
resolution and 24-25 
secondary interrupt handlers, PCI- 
based Macintosh and 86, 93, 98 
secondary interrupt level, on PCI- 
based Macintosh 86, 90 
S end S oftwareln t crru p t, 

PrepareMemoryForlO and 91 
S etCom pressedP ixMapInfo 
(QuickTime) 76, 78 
SetData, scriptable objects and 21 
SetLength, Newton Q&A 115 
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SetProperty 

scriptable objects and 

19-20,21 

transaction parameter 19-20 
SetupCardSoups, Newton Q & A 

112 

SetupRoutingSlip, Newton Q & A 

ITS 

SetValue, Newton Q & A 115 
Simone, Cai 27 
sleep mode (on a PowerBook), 
Macintosh Q & A 100 
Smith, Dave 85 
SndDoCommand 53 
SndDo Immediate 53 
SndGetlnfo {Sound Manager 3d) 
50 

SndPlayDoubleBuffer 52 
'snd r resource format 46 
software interrupt routines 

for partial preparation of 
memory 98-99 
on PCI-based Macintosh 
computers 86 

Sound Export Options dialog 54 
Sound Header 46 
Sound Manager 45 55 

compressed audio 46-48, 

49, 53-55 

controlling pitch 5 ] -52 
controlling volume 50-51 
determining hardware 
settings 50 

determining sound format 46 
playing continuous sound 53 
and QuickTime performance 

48-50 

using QuickTime to play 
sounds 52-53 
sound header 47-48 
Sound Manager 3.1 45 
“Sound Secrets” (Olson) 45-55 
SoundSecrets application 45, 46, 
50, 51,52, 53 
“Speeding Up whose Clause 
Resolution In Your Scriptable 
Application” (Anderson) 6-26 
spot light (QuickDraw 3D), 
Macintosh Q & A 105-106 
standard file dialogs, nesting 
(Macintosh Q & A) 109 
Standard File Package, Macintosh 
Q & A 109 

Standard Object Model (SOM) 
octet 34 

Open Doc and 31,36 


status dialogs 59, 61-62 
status messages 64-65 
StdPix bottleneck (QuickDraw) 
73-74, 76-77, 78 
stop alerts 61 

storage model (OpenDoc) 30-41 
storage unit cursor (OpenDoc) 33 
storage unit references (OpenDoc) 

34-35 

storage units (OpenDoc) 30, 
31-35 

cloning 34 
focusing 32-33 

storage unit views (OpenDoc) 33 
structured storage model 
(OpenDoc) 30-41 
system modal alerts 60 

T 

TAbstractScriprableObjeet class 
properties defined in 19 
scripting and 17, 18 
task (non-interrupt) level, on PCI- 
based Macintosh 86, 90 
TempNewI landle (QuickTime) 80 
TEntireContents class 21,24 
TEveryltemProxy class 21 
TEveryltem: :Search Deep 25 
'TEXT' file type (QuickDraw 3D) 
43 

'Thompson, Nick 42 
3D debugger (QuickDraw 3D) 44 
'3DMF' file type (QuickDraw 3D) 

43 

TMarkToken class 21 
TMarkTokenuSearchDeep 25 
token collections, scriptable 
objects and 8, 21-22 
tokens (of object accessor 
callbacks) 8, 17 
grouping 8, 21-22 
mark token 8, 9 
memory management of 1 7 
proxy tokens 21-22 
removing 9 , 17 
Tool Server 69-71 

Apple events and 71 
AppleScript and 71 
input and output 70-71 
modularity and factoring 
69-70 

packaging commands for use 
with 71 

redirecting errors 70-71 
standalone scripts and 71 
TProxyToken class 21-22 


tracker object (QuickDraw 3D) 43 
typeCompDescriptor descriptor, 
parameters contained in 12 
typeObjectSpecifier descriptor, 
QSL and 8 

typeWhoseDescriptor descriptor, 
typeAERecord and 11 

u 

Undo, Newton Q & A 116 
UnionSoupiAdd, Newton Q & A 

113-114 

userConfignration, Newton 
Q& A 113 

V 

values (of OpenDoc properties) 

32, 33 

adding data to 34 
of content properties 38 
manipulating value data 

33-34 

vertices in a mesh (QuickDraw 
3D), Macintosh Q & A 105 
“Veteran Neophyte, The” 

(Johnson), The Right Tool for 
die Job 110-111 
virtual memory 

PCI device drivers and 85 
remapping addresses 85 
“Virtual Memory on the 
Macintosh” (Smith) 85 
voIumeCmd command (Sound 
Manager) 50-51 
sample values for 51 

w 

whose clause 

OSL support for 7 
speeding up resolution 6-26 
versus loop-based scripts 6-7 
whose clause resolution 6-26 
optimizing 23-25 
OSL and 7, 10-15 
sample application 15-17 
See also scriptable objects 
whose descriptor 10 

contents of 11-12, 13 
interpreting the contents of 
13-14 

parsing 12-15 

wireframe Tenderer (QuickDraw 
3D), Macintosh Q & A 105 
wrapping of parts (of OpenDoc 
documents) 37 
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RESOURCES 


Apple provides a wealth of information, 
products, and services to assist 
developers. A PDA, Apple's source for 
developer tools , and Apple Developer 
University are open to anyone who 
wants access to development tools and 
instruction. Developers may access 
additional information and services 
through Apple's Developer Programs, 


APDA To order products or receive o 
complimentary catalog, call 1-800-282- 
2732 in the U.S., 1-800-637-0029 in 
Canada, (716]871-6555 internationally, or 
(716)871-651 1 For Fax. You can also order 
electronically (AppleLink APDA; Internet 
opdo@appleljnk.apple.com; America Online 
APDAorder; or CompuServe 76666,2405) 
or write APDA, Apple Computer, Inc., P.O. 
Box 319, BuFfalo, NY I4207Y)319. 


APDA offers worldwide access to 
development tools, resources, 
training products, and information 
for anyone interested in developing 
applications on Apple platforms. 
Customers periodically receive the 
Apple Developer Took Catalog 
featuring hundreds of Apple and 
third-party development products. 
There are no membership fees. 
APDA offers convenient payment 
and shipping options, including site 
licensing. 

Apple Developer University 

(DU) provides courses to get you 
started programming on Apple 
platforms and Mac OS-compatible 
hardware, as well as advanced, in- 
depth training on new technologies 
such as QuickTime VR, QuickDraw 
3D, OpenDoc, Apple Guide, and 
Newton. In addition to classroom 
training, multimedia self-paced 
courses and low-cost mini-course 
tutorials are available through APDA. 

The Macintosh Associates 
Program is a low-cost self-support 
program that provides information 
on new technologies and discounts 
on equipment. It's the primary 7 
program for Macintosh developers 
who don't need programming-level 
technical support from Apple. 

The Macintosh Associates Plus 
Program In addition to technical 
information and discounts on 
equipment, this program enables 
Macintosh developers to have up to 


Apple Developer University (DU) 

Course descriptions and schedules can be 
found in the Developer Services areas on 
AppleLink (Developer Support), eWorld 
(Apple Customer Center), and the Internet 
(World Wide Web at http;//www.apple.com). 
Or call (408)9744897, Fax (408)974- 
0544, AppleLink DEVUNIV, or write lo DU 
at Apple Computer, Inc., 1 Infinite Loop, 
M/S 305-1TU, Cupertino.. CA 95014 


ten programming-level technical 
support questions answered (via 
e-mail) per year. It also includes 
technology seeding and a subscription 
to the Mac OS Software Developer’s 
Kit. 

The Macintosh Partners Program 

is for Macintosh developers who 
need unlimited programming-level 
technical support (via e-mail). The 
program also includes technology 
seeding, a subscription to the Mac 
QS Software Developer's Kit, and 
more. 

The Newton Associates Program 

is a low-cost self-support program 
for Newton developers who don't 
need programming-level technical 
support from Apple. 

The Newton Associates Plus 
Program enables Newton developers 
to have up to ten programming- 
level technical support questions 
answered (via e-mail) per year. 

The Newton Partners Program 

offers Newton developers unlimited 
program m i ng-level tech ni cal 
support (via e-mail) as well as 
hardware purchasing privileges and 
marketing opportunities. 

The Apple Multimedia Program 

is designed for developers interested 
in die emerging multimedia market. 
Program features include a quarterly 
mailing, discounts on third-party 
products, training, and events. 


Apple Developer Programs Call the 
Developer Support Center at [408)974- 
4897, AppleLink DEVSUPPORT, or write 
1 Infinite Loop, M/S 3G3-2T, Cupertino, CA 
9501 4, for information or an application 
form. Developers outside the U.S. and 
Canada should instead contact the Apple 
office in their country for information about 
developer programs. 







Apple Computer, Inc. 

1 Infinite Loop 
Cupertino, CA 95014 















